Puppeteer Cookie Source Scheme: What It Means

sourceScheme records the scheme of the origin that originally set a cookie. It is separate from the cookie’s secure attribute: secure is the cookie’s Secure flag, while sourceScheme describes the scheme associated with the cookie’s source. Puppeteer defines 'Unset', 'NonSecure', and 'Secure'. The field is optional, Chrome-only in Puppeteer’s API documentation, and experimental in the Chrome DevTools Protocol (CDP). For ordinary cookie setup, usually provide a suitable url and let the browser establish defaults.

1. What sourceScheme means

A cookie can carry information about the scheme of the origin that originally set it. Puppeteer exposes that metadata as sourceScheme. The documented type is:

type CookieSourceScheme = 'Unset' | 'NonSecure' | 'Secure';

The values describe the cookie’s source scheme category. They are not aliases for http, https, or the cookie’s secure flag. Puppeteer documents Unset as a temporary compatibility value that lets protocol clients emulate legacy cookie scope for the scheme; it says this behavior will be removed in the future. Avoid depending on it as a durable default. See the official CookieSourceScheme reference.

2. sourceScheme vs. secure

Field	What it represents	Practical guidance
secure	The cookie’s Secure flag.	Set it according to the cookie behavior your application requires.
sourceScheme	The scheme of the origin associated with where the cookie was originally set.	Usually leave it to the setting context unless you have a specific protocol-level reason to supply it.

CDP models these as distinct cookie properties. Do not assume that setting one sets, replaces, or overrides the other. Nor should you infer from sourceScheme alone whether a cookie will be sent on a particular request: cookie behavior also involves fields such as domain, path, sameSite, secure, and the request and setting contexts. The cited references do not define sourceScheme as a substitute for those rules. See the CDP Network protocol definition.

3. Set a cookie with Puppeteer

In the page-level cookie API, sourceScheme is optional. The url used to set a cookie can affect default domain, path, and source-scheme values. A typical example of explicitly supplying the field looks like this:

await page.setCookie({
  name: 'session',
  value: 'example',
  url: 'https://example.test',
  secure: true,
  sourceScheme: 'Secure',
});

This is an illustrative example, not a claim that it was executed. For routine setup, omit sourceScheme unless your application has a specific reason to pass the protocol metadata. The setting URL and browser context can provide defaults. Check the current Puppeteer CookieParam reference for the API details and support caveat.

Value choices

• 'Secure': identifies the secure source-scheme category.
• 'NonSecure': identifies the non-secure source-scheme category.
• 'Unset': a temporary legacy-compatibility state; do not choose it casually for new code.

The enum’s names and source-scheme description explain what these values communicate. They do not, by themselves, establish a complete rule for cookie delivery or override other cookie attributes.

4. Browser and protocol compatibility

Puppeteer’s page-level CookieParam and browser-level CookieData references mark the field optional and supported only in Chrome. The CDP Network definition marks it experimental. If an application sets or reads this field explicitly, verify the Puppeteer and Chrome versions it uses and handle unsupported or changed protocol behavior appropriately.

The linked Puppeteer references may describe different documentation versions, and the CDP link points to the moving master branch. Treat them as API references to check against your installed versions, not as one synchronized release snapshot.

5. Troubleshooting

Symptom	Likely cause	What to check or change
The cookie object has a sourceScheme you did not set.	The browser or protocol context supplied source metadata.	Interpret it as metadata about the scheme of the origin that originally set the cookie; it is not the secure flag.
Your code or protocol client rejects sourceScheme.	The API or browser version may not support the field, or the implementation may not be Chrome.	Check the installed Puppeteer API and Chrome version. Puppeteer documents this field as Chrome-only; CDP marks it experimental.
Cookie behavior differs from what you expected.	A separate cookie attribute or context may be responsible.	Inspect secure, sameSite, domain, path, and the setting url. The references do not say that sourceScheme overrides them.
Code depends on 'Unset'.	Unset is a temporary legacy-compatibility option.	Use a documented scheme value only when you have a concrete protocol need; otherwise omit the optional field and let the setting context establish defaults.

6. Reliability and operational notes

• Prefer contextual defaults: Supplying the cookie’s url gives Puppeteer and the browser context information that can affect default domain, path, and source scheme.
• Keep fields distinct: Record or configure secure and sourceScheme for their separate meanings. Do not use one as a proxy for the other.
• Account for support: Guard explicit protocol-field use where the browser or Puppeteer version may differ. The documentation establishes Chrome-only support, not identical behavior across all browser implementations.
• Do not assume delivery semantics: Diagnose an unexpected cookie request by reviewing the complete cookie and request context, rather than attributing it to this field alone.

7. Or skip the browser setup

If your task is to capture a page rather than manage its cookies in Puppeteer, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF; its capture flow accepts cookie and consent banners and removes supported banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See the API documentation.

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}`);

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

8. FAQ

Does sourceScheme: 'Secure' mean the cookie has secure: true?

No. They are separate properties. secure is the cookie’s Secure flag; sourceScheme describes the source origin’s scheme category.

Should I set sourceScheme on every cookie?

No. It is optional. Use the setting URL and browser context for defaults unless you have a specific protocol-level reason to supply it.

Can I rely on 'Unset' for new code?

Avoid treating it as a permanent default. Puppeteer describes it as a temporary legacy-compatibility option that will be removed in the future.

Is the field supported in every browser Puppeteer can control?

Puppeteer’s API reference says it is supported only in Chrome. Check the documentation for your installed version and browser.