Puppeteer Cookie Priority Explained

priority is an optional cookie field in Puppeteer. Puppeteer documents it as supported only in Chrome; Chrome DevTools lists Low, Medium (the default), and High, while marking the Priority attribute deprecated. Treat it as cookie metadata: it does not decide which matching cookie a request sends, replace domain or path matching, or override Secure and SameSite rules.

For current Puppeteer code, set cookies on the browser or the browser context that will use them. Page.setCookie() is obsolete. The example below creates an isolated context, sets a High-priority cookie, reads it back, navigates, and closes the context.

1. What does Puppeteer cookie priority mean?

Puppeteer exposes priority on both its page-level CookieParam and browser-level CookieData types. The documented values are Low, Medium, and High. If omitted, Chrome uses Medium.

The name can sound like a request ordering or conflict-resolution rule. The documentation reviewed does not establish that interpretation. In particular, do not rely on High to make a cookie win over another cookie with the same name, to be sent first, or to be retained under storage pressure. The documentation does not provide a complete current eviction algorithm or a retention guarantee.

Chrome DevTools labels the Priority attribute deprecated. Since the behavior and documentation can change by browser version, use this field only when you have a Chrome-specific reason and verify it in the Chrome version you target. Puppeteer documents the field as Chrome-only; do not assume another browser honors it.

2. Set priority with the current Puppeteer API

Install Puppeteer in a Node.js project with npm install puppeteer. The standard Puppeteer package downloads a compatible Chrome for Testing browser. Save the following as cookie-priority.mjs and run it with node cookie-priority.mjs.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
const context = await browser.createBrowserContext();

try {
  const page = await context.newPage();

  await context.setCookie({
    name: 'session_hint',
    value: 'example-value',
    url: 'https://example.com/',
    priority: 'High',
    secure: true,
    httpOnly: true,
    sameSite: 'Lax',
  });

  const cookies = await context.cookies('https://example.com/');
  console.log(cookies.find((cookie) => cookie.name === 'session_hint'));

  await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });
} finally {
  await context.close();
  await browser.close();
}

Use priority: 'Low' or priority: 'Medium' if those values fit your Chrome-specific use case. Omitting the field leaves the documented default in effect. The API expects the named string values; do not use numeric levels.

The code sets the cookie before navigation. The url attribute gives Puppeteer a URL from which to derive its scope. You can instead specify domain and path explicitly, subject to cookie rules. Do not provide conflicting scope fields. Use the browser or context cookie API that corresponds to the store used by the page or request; browser contexts isolate storage.

3. Cookie fields that determine whether a cookie applies

Priority is separate from the attributes that define scope, transport, expiry, script access, or partition context. Check those fields when a cookie is missing or unexpectedly sent.

Field	What it controls	Practical check
domain and path	Which hosts and URL paths the cookie is scoped to.	Check the request hostname and path against the cookie scope. A priority value cannot broaden either scope.
secure	Whether the cookie is restricted to secure connections.	Use HTTPS when testing a Secure cookie.
sameSite	Whether the cookie is eligible in same-site or cross-site contexts.	For cross-site use in Chrome, specify SameSite=None and Secure. Chromium documents unspecified SameSite as treated as Lax in the described Chrome behavior.
expires	Persistent expiry time.	Omitting it makes the cookie a session cookie; check for expired timestamps and units when supplying it.
httpOnly	Whether page JavaScript can access the cookie.	An HttpOnly cookie can still be used by eligible requests while being absent from document.cookie.
partitionKey	Partition context for a partitioned cookie; Puppeteer documents browser-specific semantics.	Set and inspect it in the intended top-level-site context when testing partitioned behavior.
priority	Chrome-only priority metadata in Puppeteer’s API.	It does not replace any of the scope and sending checks above.

SameSite eligibility is independent of priority. A High-priority cookie can still be excluded because its domain, path, Secure, SameSite, expiry, or partition conditions do not fit the request.

4. Choose the right cookie store

• Browser context: Use context.setCookie() when the cookie belongs to pages in a particular context. Read it with context.cookies(), and delete it with the corresponding context cookie API.
• Browser: Use browser.setCookie() when you intentionally want to work at browser level. Keep the target context and navigation in mind; contexts isolate storage.
• Page: Avoid page.setCookie() in new code. Puppeteer marks it obsolete and points to browser- or context-level cookie methods.

For a test that needs a clean cookie store, create a fresh browser context, set the cookie there, and perform the navigation in a page from that context. A cookie set in a different context will not automatically appear in the one under test.

5. Common problems and fixes

Symptom	Likely cause	Fix
TypeScript rejects the priority value	The value is misspelled, has the wrong case, or the installed Puppeteer type definitions differ from the version in the example.	Use the documented strings 'Low', 'Medium', or 'High'; check the API types for your installed Puppeteer version.
The cookie is absent after setting it	It was set in another context, has mismatched domain/path scope, or was already expired.	Set and read it through the same browser context, inspect the returned cookie data, and verify the intended URL and expiry.
The cookie exists but is not sent	Secure, SameSite, scope, expiry, or partition rules make it ineligible for the request.	Inspect those attributes and the request context. Priority does not override them.
document.cookie does not show the cookie	The cookie may be HttpOnly.	Read it through Puppeteer’s cookie API. HttpOnly deliberately limits page JavaScript access.
A cross-site request omits the cookie	SameSite policy can exclude it; Chrome requires SameSite=None together with Secure for cross-site cookies.	Set both attributes when appropriate, use HTTPS, and verify the browser’s current behavior.
Changing priority has no visible effect	Priority is metadata, browser support is Chrome-only in Puppeteer’s docs, and DevTools marks the attribute deprecated.	Do not use priority to fix a sending or matching problem. Check scope and eligibility fields; avoid relying on undocumented retention or ordering behavior.
Code reports that page.setCookie() is obsolete	The page-level API is deprecated in favor of browser-level methods.	Move the call to context.setCookie() or browser.setCookie() and use the corresponding store.

6. Performance, reliability, and version considerations

Setting or reading a cookie is a browser-protocol operation. For a single cookie, the main reliability concern is usually using the right context and attributes, not the priority value. Avoid repeatedly launching a browser just to set one cookie when your application can reuse a controlled browser and context safely; create isolated contexts where test isolation matters.

Do not build application correctness around cookie priority. The Puppeteer API describes Chrome support, while Chrome DevTools calls the attribute deprecated. Pin and review your Puppeteer and Chrome versions when behavior matters, and test cookie sending at the request boundary you care about. The reviewed official sources do not give a universal priority-based eviction order, storage threshold, or performance benefit.

Cookie priority has no direct cost setting. Operational cost comes from the browser infrastructure and workload used to run Puppeteer; this API field does not reduce requests or guarantee longer cookie retention.

7. Or skip the browser setup

If the task is capturing a page rather than automating cookie behavior, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether it was billed. Its MCP server provides screenshot, page-info, and PDF tools for AI agents.

See the ScreenshotNeo API docs. Example request:

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

ScreenshotNeo includes 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Sign up for a free ScreenshotNeo account.

8. FAQ

Is Medium the default priority?

Yes. Chrome DevTools lists Medium as the default value.

Does High priority make a cookie get sent before another cookie?

The cited documentation does not establish request-header ordering or conflict resolution by priority. Do not depend on it for that purpose.

Can I use priority in Firefox?

Puppeteer’s API reference documents the field as supported only in Chrome. Do not assume other browsers honor it.

Should I set priority on every cookie?

No. It is optional, and the attribute is marked deprecated by Chrome DevTools. Set it only for a specific Chrome-targeted need that you have verified.

Which Puppeteer method should new code use?

Use Browser.setCookie() or BrowserContext.setCookie(), matching the cookie store used for the navigation. Page.setCookie() is obsolete.

Sources

• Puppeteer CookieParam API and CookieData API document cookie fields and Chrome support.
• Chrome DevTools cookie reference lists priority values and marks Priority deprecated.
• Puppeteer cookie guide, Page.setCookie API, and BrowserContext API cover current cookie methods and isolated storage.
• Chromium SameSite FAQ explains SameSite behavior for cross-site cookies.