Puppeteer Cookie Priority: What the Values Mean

CookieParam.priority is an optional Puppeteer cookie property with three accepted values: Low, Medium, and High. Puppeteer documents it as supported only in Chrome. Chrome DevTools describes Medium as the default in its cookie table, while the Chrome DevTools Protocol (CDP) schema marks the enum experimental. These facts identify the available labels; they do not establish a precise eviction algorithm or guarantee that a high-priority cookie will be retained.

What do Puppeteer cookie priority values mean?

The documented values are priority levels, but the cited API and protocol documentation do not define a quantitative scale or explain exactly when Chrome evicts cookies at each level. Treat them as browser metadata, not as a persistence control.

Value	What the documentation establishes
Low	A valid cookie priority value. The reviewed sources do not specify a particular eviction rule for it.
Medium	A valid value. Chrome DevTools identifies it as the default shown for the deprecated cookie Priority attribute.
High	A valid value. The reviewed sources do not say it prevents deletion or guarantees retention.

Puppeteer lists priority as optional. The documentation reviewed here does not state what Puppeteer sends when you omit it, so do not infer that omission necessarily sets Medium from DevTools’ display description.

Set cookie priority with Puppeteer

Install Puppeteer in a Node.js project, then provide one of the exact, case-sensitive enum strings when setting a cookie in Chrome:

npm install puppeteer

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

    await page.setCookie({
      name: 'session_hint',
      value: 'example-value',
      url: 'https://example.com',
      priority: 'High',
    });

    const cookies = await page.cookies('https://example.com');
    console.log(cookies.find(cookie => cookie.name === 'session_hint'));
  } finally {
    await browser.close();
  }
})();

Use the cookie’s normal scope and security fields as appropriate for your application. Priority is separate from SameSite, Secure, HttpOnly, domain, path, expiry, and partition key; it does not replace or configure those properties.

Choose a value without assuming undocumented behavior

1. Use one of Low, Medium, or High; other spellings and labels are not in the documented enum.
2. Set it only when your Chrome automation needs to supply the field.
3. Test the behavior your application actually depends on. The documentation does not promise that any value changes retention in a particular way.
4. If priority is not relevant to the test, omit the optional property rather than making assumptions about its implicit value.

Browser and protocol compatibility

The Puppeteer API reference says cookie priority is supported only in Chrome. Do not rely on the property when targeting Firefox. The CDP schema labels the CookiePriority type experimental, while Puppeteer’s current API reference exposes the property. Those statements describe different layers: API availability does not make it a cross-browser guarantee or establish long-term protocol stability.

Do not confuse cookie priority with CDP network request priority. Network requests have a separate priority enum that includes values such as VeryLow and VeryHigh. Cookie priority has only the three values shown above.

What high priority does not guarantee

The official material cited here does not specify Chrome’s exact cookie eviction algorithm. In particular, it does not say that High prevents eviction, guarantees a cookie survives storage pressure, or changes whether the cookie is sent to a site. For critical session behavior, use the application’s supported session and renewal design; treat this field as a priority setting whose detailed effect is not established by these references.

Troubleshooting

Symptom	Likely cause	What to do
The cookie is rejected or the call errors	The value is misspelled, incorrectly cased, or not one of the three enum values.	Use exactly Low, Medium, or High.
The field has no effect in Firefox	Puppeteer documents priority as Chrome-only.	Do not depend on priority for Firefox automation; test browser behavior independently.
A high-priority cookie disappears	High priority is not documented as a retention guarantee.	Review cookie scope, expiry, application session handling, and browser storage behavior. Do not use priority as the sole persistence mechanism.
DevTools shows Medium although the script omitted priority	DevTools documents Medium as the default shown for the deprecated Priority attribute; that does not prove Puppeteer’s omission behavior.	Set a value explicitly if the test needs to send one, and avoid treating the DevTools display as a Puppeteer runtime contract.
A request-priority value is rejected for a cookie	Network request priority and cookie priority are different enums.	For a cookie, use only Low, Medium, or High.

Performance, reliability, and cost

The cited references provide no benchmark showing a performance difference among cookie priority values. This is a small optional cookie field; choose values for the behavior you need to investigate, and measure your own workflow if performance matters. Reliability depends on the browser and protocol support available in the environment. Pin and validate the Puppeteer and Chrome versions used by automation, especially when a test relies on experimental protocol details.

Puppeteer itself is browser automation software; this cookie setting has no ScreenshotNeo pricing implication. If your task is to capture a page rather than exercise browser cookie behavior, ScreenshotNeo offers a one-request screenshot API and MCP server. See the ScreenshotNeo website and its API documentation.

Or skip the browser setup

If your goal is a clean page screenshot rather than testing cookie priority, call ScreenshotNeo’s screenshot endpoint:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture, with each cleanup step configurable. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. See the docs, then sign up for 1,000 free screenshots a month, with no card.

FAQ

Does setting High make a login cookie permanent?

No such guarantee is documented. Cookie lifetime and application session design should not depend on this field.

Can I set a numeric priority such as 0, 1, or 2?

The documented Puppeteer and CDP values are the strings Low, Medium, and High.

Is cookie priority the same as SameSite?

No. They are separate cookie properties with different purposes; the cited sources describe priority as its own field.

Official references

• Puppeteer CookieParam API reference
• Chrome DevTools Protocol Network schema
• Chrome DevTools cookie documentation