Puppeteer CookieData: Cookie Fields Explained

CookieData is Puppeteer’s browser-level input type for setting cookies. In the Puppeteer 25.12.0 API reference, name, value, and domain are required; the other listed fields are optional. For new code, use Browser.setCookie() or BrowserContext.setCookie(). Puppeteer marks Page.setCookie() obsolete. See the CookieData API reference and BrowserContext.setCookie reference.

Runnable example: set a cookie in a browser context

This example creates an isolated browser context, sets a cookie for the target site, opens that site, and reads the cookie back. Install Puppeteer with npm install puppeteer; then run it with Node.js.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const context = await browser.createBrowserContext();
    await context.setCookie({
      name: 'theme',
      value: 'dark',
      domain: 'example.com',
      path: '/',
      secure: true,
      httpOnly: true,
      sameSite: 'Lax',
    });

    const page = await context.newPage();
    await page.goto('https://example.com/');
    console.log(await context.cookies('https://example.com/'));
    await context.close();
  } finally {
    await browser.close();
  }
})();

Use a domain that is valid for the site you intend to visit. Setting a cookie does not log a user in by itself: the target application must recognize the cookie name and value, and the cookie’s scope and flags must allow it to accompany the request.

CookieData fields at a glance

The following meanings reflect Puppeteer’s 25.12.0 CookieData API reference. Some fields are browser-specific; see the notes below before relying on them outside Chrome.

Field	Required?	Meaning and practical note
name	Yes	The cookie’s name.
value	Yes	The cookie’s value. The application decides what the value means.
domain	Yes	The domain supplied to this browser-level API. Cookie domain rules determine which hosts receive it; a domain string does not automatically mean every related host is in scope.
path	No	Limits which request paths match. It is not a security boundary.
expires	No	Expiration time as a number in Puppeteer’s interface. If omitted, Puppeteer describes the cookie as a session cookie. This interface does not list HTTP Max-Age as a property.
httpOnly	No	When true, non-HTTP cookie APIs such as browser scripting APIs cannot access the cookie. This is separate from secure.
secure	No	When true, the cookie is restricted to secure channels. It primarily protects confidentiality and does not address every integrity risk.
sameSite	No	SameSite setting: Strict, Lax, None, or Default in Puppeteer’s documented type. Browser behavior and defaults can evolve.
partitionKey	No	Partitioned-cookie context. Puppeteer documents a sourceOrigin and optional hasCrossSiteAncestor; support and mappings are browser-specific.
priority	No	Cookie priority. Puppeteer documents this as supported only in Chrome.
sourceScheme	No	Source scheme enum. Puppeteer documents Chrome-only support. Its Unset value is temporary compatibility behavior slated for removal.

Scope and lifetime: domain, path, and expires

Domain

domain is required by CookieData. Cookie scope follows cookie domain rules: a host-only cookie and a cookie carrying a Domain attribute do not have identical scope. Do not assume that supplying a parent-looking domain makes a cookie valid for arbitrary subdomains. For the page-level CookieParam, the url field can affect default domain, path, and source scheme; CookieData has no url field.

Path

path controls path matching for requests. A cookie with path: '/account' is intended for matching paths under that area, while '/' is the broad site path. The cookie standard cautions that Path cannot be relied on for security: use application authorization and appropriate cookie flags for protection.

Expiration

expires is represented as a number by Puppeteer. If you omit it, Puppeteer documents the cookie as a session cookie. This is distinct from the HTTP Max-Age attribute, which is not one of the listed CookieData fields. An expiry date does not guarantee that a browser will retain a cookie until that date; user agents may evict cookies earlier.

Access and transport: httpOnly, secure, and sameSite

• httpOnly: true limits access through non-HTTP cookie APIs, including browser scripting APIs. It does not make a cookie secure in transit by itself.
• secure: true restricts the cookie to secure channels. It is independent of httpOnly, so a cookie can use both.
• sameSite controls cross-site sending behavior. Puppeteer’s documented values are Strict, Lax, None, and Default. Choose deliberately for the site’s cross-site flows, and consult current browser behavior when a flow depends on it.

The foundational cookie standard describes the distinction this way: “The HttpOnly attribute limits the scope of the cookie to HTTP requests.” See RFC 6265, section 4.1.2.6. The RFC is a foundational description, not a complete account of newer browser features such as partitioned cookies.

Partition and source fields

partitionKey identifies partition context for a partitioned cookie. Puppeteer documents a sourceOrigin and optional hasCrossSiteAncestor, along with Chrome-specific mappings and support. Do not assume identical semantics across browser engines.

priority and sourceScheme are documented as Chrome-only. The Unset source scheme is described as temporary compatibility behavior slated for removal. Avoid depending on these fields in portable automation unless the browser and Puppeteer version are controlled.

CookieData vs CookieParam

Question	CookieData	CookieParam
API level	Browser or browser context cookie setting	Page-level cookie parameter type
Is domain required?	Yes in the documented type	No
Does it have url?	No	Yes, optional; Puppeteer says it can affect default domain, path, and source scheme
Which setter should new code use?	Browser.setCookie() or BrowserContext.setCookie()	The old page setter is obsolete; use browser/context APIs

See the versioned CookieData and CookieParam references, plus the Page.setCookie API note.

Set several cookies or use the browser-level setter

Browser.setCookie(...cookies) sets cookies in the default browser context. Use the context setter when you created or selected a specific context, so the cookie goes into the same isolated session as the pages you will navigate.

await context.setCookie(
  { name: 'locale', value: 'en', domain: 'example.com', path: '/' },
  { name: 'layout', value: 'compact', domain: 'example.com', path: '/' }
);

// Or set cookies on the browser's default context:
await browser.setCookie({
  name: 'notice',
  value: 'dismissed',
  domain: 'example.com',
  path: '/',
});

The Puppeteer cookie guide covers getting, setting, and deleting cookies: Manage cookies. For cleanup, use the corresponding context or browser cookie deletion API documented for your installed version.

Troubleshooting

Symptom	Likely cause	What to check
TypeScript says domain is missing	CookieData requires it, even though CookieParam makes it optional.	Provide a domain appropriate for the intended site, or use the correct API and type for the operation.
The cookie is absent on the next request	Domain or path does not match, the cookie was set in a different context, or the target request does not meet its flags.	Set it on the same context as the page; inspect the cookie with the context cookie API and verify the request URL, domain, path, secure channel, and SameSite behavior.
JavaScript cannot read the cookie	httpOnly is true.	This is expected for an HTTP-only cookie. Check it through browser cookie APIs or server requests instead of document.cookie.
A cookie set for HTTPS is unavailable on HTTP	secure: true restricts it to secure channels.	Use HTTPS for the target flow; do not remove the flag from production authentication cookies just to make an insecure test pass.
Cross-site login or embedded flow fails	The SameSite setting or current browser policy may prevent the cookie from accompanying the request.	Confirm the intended cross-site behavior and choose an appropriate documented value; test in the browser engine and version used in deployment.
Cookie does not appear on a related subdomain	Cookie scope is narrower than assumed; a host-only cookie is not automatically shared with all subdomains.	Review the domain rules and use an allowed scope for the site. Do not use Path as an access-control mechanism.
Partition or source field is rejected or ignored	Browser support differs; priority and source scheme are Chrome-only in Puppeteer’s reference.	Check the field’s versioned documentation and run against the supported browser. Omit browser-specific fields when portability matters.
Cookie disappears before its expiry	Expiry is not a guaranteed retention promise; browsers may evict cookies earlier.	Do not use client cookie retention as durable storage. Refresh or reissue state through the application when appropriate.

Reliability, security, performance, and cost notes

• Reliability: Set cookies in the context that will make the request, and do it before navigation when the first request must carry them. Verify the resulting cookie and the actual request behavior instead of assuming that a successful setter call means the server accepted the session.
• Security: Keep authentication values out of logs and source control. Use httpOnly and secure according to the application’s needs; they solve different problems. Do not treat path as a security boundary.
• Performance: Cookie setup is usually a small part of browser automation. Reuse a context for a coherent session, but use separate contexts when session isolation is required. Avoid adding unnecessary browser-specific cookie fields.
• Cost: Self-hosted Puppeteer has no per-screenshot API charge, but you provide and operate the browser runtime and its compute. A hosted screenshot API trades local browser setup for a service charge; compare the actual volume and requirements before choosing.

Or skip the browser setup

If your goal is to capture a page rather than manage its browser session, ScreenshotNeo is a website screenshot API and MCP server. Its API accepts a URL and returns an image or PDF; see the API documentation.

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

Cookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server lets AI agents use screenshot, page-info, and PDF tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Is domain required in CookieData?

Yes, in Puppeteer 25.12.0’s documented CookieData type. The separate CookieParam type makes it optional.

Should I still call Page.setCookie()?

No for new code: Puppeteer marks it obsolete and points to browser or context cookie methods.

Does expires accept a date string?

The documented interface represents it as a number. Follow the installed Puppeteer version’s type definition when constructing that value.

Can Puppeteer use these fields identically in every browser?

No. The API specifically documents Chrome-only support for priority and sourceScheme, and partition behavior is browser-specific.