Puppeteer Cookie Partition Keys Explained

Direct answer: In Puppeteer, a cookie’s partitionKey identifies the top-level site context in which a partitioned cookie is available. In Chrome, Puppeteer’s CookiePartitionKey.sourceOrigin maps to CDP’s topLevelSite; optional hasCrossSiteAncestor describes whether the cookie has cross-site ancestors. These fields matter for cookies using CHIPS, Chrome’s partitioned-cookie mechanism. Puppeteer CookiePartitionKey reference

What a cookie partition key means

A partition key is context, not a cookie name or a replacement for the cookie’s domain. Chrome describes a partitioned cookie as double-keyed: by the host key of the site that set it and by the top-level site where it was set. An embedded service can therefore have separate cookie state when it appears under different top-level sites. A cookie set while the service is embedded on one site is not available to that service when embedded on a different top-level site. Chrome CHIPS documentation

For example, if widget.example is embedded on shop.example and news.example, its partitioned state is isolated by the top-level site. Partitioning is not a way to share one cookie across unrelated top-level sites.

Puppeteer’s cookie types and field names

Type or field	Meaning
CookiePartitionKey	Object with sourceOrigin and optional hasCrossSiteAncestor. In Chrome, sourceOrigin maps to CDP’s topLevelSite.
CookieData.partitionKey	Optional browser-level cookie field. The documented input accepts a CookiePartitionKey or a string.
CookieParam.partitionKey	Optional page-level cookie field. Its browser semantics vary; Puppeteer documents Firefox matching the source origin in its PartitionKey.
hasCrossSiteAncestor	Optional flag supported only in Chrome according to Puppeteer’s reference.

Use the cookie shape expected by the Puppeteer method you call. Browser-level CookieData and page-level CookieParam are related but distinct API types. Check the reference matching your installed Puppeteer version before relying on a field or method signature. CookieData · CookieParam

Set a partitioned cookie with Puppeteer

The following runnable Node.js example launches Chromium, opens a page on a top-level site, and sets a page cookie with a partition key. The cookie is marked Secure and SameSite=None, as required for the typical cross-site embedded-cookie use case. Run npm install puppeteer, then save this as partitioned-cookie.js and run node partitioned-cookie.js.

const puppeteer = require('puppeteer');

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

    await page.setCookie({
      name: '__Host-widget-session',
      value: 'example-session',
      url: 'https://widget.example/',
      secure: true,
      httpOnly: true,
      sameSite: 'None',
      partitionKey: {
        sourceOrigin: 'https://shop.example',
        hasCrossSiteAncestor: true
      }
    });

    console.log(await page.cookies('https://widget.example/'));
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

This example uses the page-level cookie parameter shape. A page-level partitionKey is documented by Puppeteer, but details can depend on Puppeteer and browser versions. If the installed version rejects the object form, consult that version’s CookieParam reference; CookieData separately documents accepting a partition key object or string.

For a real third-party cookie, the server can set it in an HTTP response with the CHIPS attribute. Chrome’s documented example is:

Set-Cookie: __Host-name=value; Secure; Path=/; SameSite=None; Partitioned;

Chrome requires Secure on partitioned cookies and recommends the __Host prefix to bind the cookie to the hostname. CHIPS requirements and examples

Choose the correct top-level site

1. Identify the top-level URL in the browsing context when the cookie-setting request starts.
2. Use that site context for the partition key. In Puppeteer’s Chrome-facing interface, supply it as sourceOrigin.
3. Set the cookie for the embedded service’s own URL or domain as appropriate; the partition key does not replace the cookie’s host scope.
4. If the cookie is set through a cross-site ancestor context, set hasCrossSiteAncestor when needed and supported by the browser/API version.
5. Verify behavior in the actual browser and Puppeteer version used in deployment.

Do not copy a partition key from one embedding site and expect the same partitioned state on another. That separation is the purpose of CHIPS.

Chrome and Firefox differences

Puppeteer’s documentation describes Chrome’s partition key in terms of the top-level site. It describes Firefox differently: Firefox’s partitionKey matches the source origin in the browser’s PartitionKey. The optional hasCrossSiteAncestor property is documented as Chrome-only. Avoid assuming that a Chrome key object has identical semantics across browsers. Puppeteer CookieParam reference

Chrome’s extensions API also uses the name topLevelSite. Its version notes apply to that extensions API: the reference marks partition-key filtering and modification as Chrome 119+, and getPartitionKey() as Chrome 132+. Those markers do not establish Puppeteer’s minimum version. Chrome cookies API

Do-it-yourself workflow and alternatives

When the task is specifically cookie behavior, Puppeteer gives you control of the browser context and cookie inputs. For a screenshot of a page, however, you may not need to install or operate a browser locally.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers, made by Yorker Media. Its one-call GET endpoint returns an image or PDF. It is an alternative to try first when your goal is a page capture: cookie banners, popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are never billed; and an MCP server lets AI agents take screenshots. One thousand screenshots a month are free with no card, and paid plans start at $5 for 3,000. It does not expose Puppeteer cookie partition controls.

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo offers PNG, JPEG, WebP or PDF output and options including full-page capture, element capture, device and viewport settings, custom CSS and JavaScript, waits, headers, cookies, caching, signed links, asynchronous jobs and bulk capture. Plans include Free (1,000 shots/month), Starter ($5 for 3,000), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000) and Business ($249 for 1,000,000); yearly billing gives two months free, and every feature is available on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

Troubleshooting

Symptom	Likely cause	What to check
The cookie is rejected or absent	Cookie attributes or URL scope do not match the target browser context.	For cross-site CHIPS usage, check Secure, SameSite=None, the cookie URL/domain, and the partition key’s top-level site.
Cookie appears on one embedding site but not another	Expected partitioning behavior.	Each top-level site has its own partition. Set or inspect the cookie in the intended top-level context.
TypeScript rejects partitionKey or its shape	Installed Puppeteer declarations differ from the reference or method input.	Check the installed package’s CookieParam or CookieData type and use the type required by that method.
hasCrossSiteAncestor is ignored or unsupported	Browser semantics differ; Puppeteer documents it as Chrome-only.	Omit it for unsupported browsers and verify the Chrome-facing API version.
Chrome examples do not behave the same in Firefox	Partition-key semantics differ across browsers.	Follow Puppeteer’s browser-specific description; Firefox matches source origin in its PartitionKey.
Cookie is missing after navigation	The request may be in a different page, browser context, top-level site, or origin scope.	Set and inspect cookies in the same intended context, and verify the cookie’s host/path and partition key.

Performance, reliability and cost

Partition keys are a cookie-scoping detail; they do not make Puppeteer navigation or capture intrinsically faster. For reliable automation, pin and record the Puppeteer and browser versions, use the same browser engine as production, and explicitly close the browser in a finally block. Wait for the page state your task needs rather than treating navigation completion as proof that a third-party cookie was accepted.

Running Puppeteer means provisioning a browser process and its runtime environment. ScreenshotNeo instead charges only for clean shots: bot checks/CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies outcomes with X-Page-Verdict and X-Billed headers. Pick the route according to the job: Puppeteer for browser and cookie control; the API for managed screenshot output.

FAQ

Is partitionKey the same as a cookie domain?

No. The cookie’s host/domain scopes which setting site owns it; the partition key scopes its availability by top-level-site context.

Can one partitioned cookie be shared across unrelated top-level sites?

No. CHIPS isolates the embedded service’s cookie state by the top-level site where it was set.

Does Chrome’s extensions API minimum version tell me which Puppeteer version I need?

No. The Chrome 119 and 132 markers in the cited reference describe the extensions cookies API, not Puppeteer’s minimum supported version.

Should I use CHIPS for state shared by related websites?

Do not assume so. Chrome’s CHIPS documentation describes Related Website Sets using the Storage Access API and says that design does not integrate with CHIPS partitioning.