Puppeteer Cookie Source Schemes Explained

CookieSourceScheme is Puppeteer’s three-value type for the scheme of the origin that originally set a cookie: 'Unset', 'NonSecure', or 'Secure'. The field is optional, documented as supported only in Chrome, and separate from the cookie’s secure boolean. Unset is described as a temporary compatibility behavior for protocol clients emulating legacy cookie scope; Puppeteer says it will be removed, but gives no removal date. Puppeteer CookieSourceScheme reference.

What does sourceScheme mean?

It records the source scheme associated with the origin that set the cookie. Puppeteer documents it as metadata about the cookie’s originating site, not as another name for the cookie’s secure property. The two are listed separately in the cookie parameter API. CookieParam reference.

The documented TypeScript union is exactly:

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

The names describe whether the source scheme is secure or non-secure, or whether the legacy unset behavior is used. The API reference does not specify a universal mapping between this field and secure, so do not infer one for combinations it does not document.

Meaning of each value

Value	Documented meaning	Practical guidance
Secure	The source origin scheme is secure.	Use when your Chrome cookie-setting context calls for recording a secure source scheme.
NonSecure	The source origin scheme is non-secure.	Use when the source context is non-secure and you specifically need to provide this metadata.
Unset	A temporary protocol-client compatibility behavior for emulating legacy cookie scope.	Do not choose it as a general default. Prefer allowing Puppeteer and the cookie context to determine behavior unless compatibility requires it.

Puppeteer’s reference does not define every browser’s internal handling or prescribe an application-level default. Check the documentation for the Puppeteer version installed in your project before depending on this field.

Where the property appears

sourceScheme is optional on both the page-level CookieParam input and browser-level CookieData interface. Both references label it as supported only in Chrome. This is not a portable cross-browser cookie setting. CookieData reference.

When setting a CookieParam, the url field can affect the default domain, path, and source scheme. That means explicitly supplying sourceScheme may be unnecessary when you already provide the cookie’s URL and rely on defaults. The docs do not promise the same behavior across browsers.

Set a cookie with Puppeteer

Install Puppeteer in a Node.js project:

npm install puppeteer

This runnable example launches Puppeteer, opens a page, and sets a cookie with an explicit source scheme. Use a URL and scheme appropriate to your own test environment; this example uses a secure origin.

const puppeteer = require('puppeteer');

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

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

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

sourceScheme is optional. Remove that property to let Puppeteer use the documented cookie context and defaults. The example sets secure: true as a separate cookie attribute; it does not claim that this boolean and sourceScheme are interchangeable.

TypeScript example

With Puppeteer’s types available, the string values are checked against the documented union:

import puppeteer, { type CookieParam } from 'puppeteer';

const cookie: CookieParam = {
  name: 'session_hint',
  value: 'example-value',
  url: 'https://example.com',
  sourceScheme: 'Secure',
};

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await page.setCookie(cookie);
  } finally {
    await browser.close();
  }
})();

The API type allows the property, but the documentation’s Chrome-only note still applies at runtime.

Choosing whether to set it

1. Start with the cookie’s actual URL. Provide url when it correctly represents the target context. Puppeteer documents that it can affect default domain, path, and source scheme.
2. Leave the field out unless you need to control it. It is optional. Avoid adding metadata just because the field exists.
3. If you set it, use one of the exact values. The API accepts Unset, NonSecure, or Secure, with the documented capitalization.
4. Use Unset only for a compatibility need. Puppeteer describes it as temporary legacy-scope emulation, not the recommended general-purpose setting.
5. Check browser and package versions. The property is documented as Chrome-only, and references should match your installed Puppeteer version.

Common mistakes and troubleshooting

Symptom	Likely cause	Fix
TypeScript rejects the value.	The string is misspelled, has different capitalization, or is outside the three-value union.	Use exactly 'Unset', 'NonSecure', or 'Secure'.
The property is ignored or behaves differently outside Chrome.	Puppeteer documents sourceScheme as Chrome-only.	Do not rely on it for cross-browser behavior; consult the API docs for the browser and Puppeteer version in use.
The cookie does not behave as expected after setting sourceScheme.	The field may have been confused with the separate secure attribute, or another cookie property/context may be responsible.	Inspect secure, the cookie URL/domain/path, and the page origin independently. The reference does not define a universal mapping between the two fields.
A cookie is scoped unexpectedly.	The provided URL can affect defaults for domain, path, and source scheme.	Check the URL and explicitly set the cookie scope fields you need, following the CookieParam documentation.
Legacy behavior changes after a Puppeteer upgrade.	Unset is documented as temporary and slated for removal, with no published removal date.	Do not build new behavior around Unset unless compatibility requires it. Review the version-matched release documentation when upgrading.

Performance, reliability, and cost

sourceScheme is cookie metadata; the Puppeteer references do not report a measurable performance impact, reliability guarantee, or cost associated with choosing one value. Avoid treating an undocumented performance or browser behavior claim as part of the API contract. For repeatable automation, keep the browser, Puppeteer version, origin URL, and cookie attributes explicit, and record which browser is under test.

Or skip the browser setup

If your goal is to inspect a rendered page rather than manage Puppeteer cookies, ScreenshotNeo returns a screenshot or PDF from one GET request. Its API can capture a page without setting up a browser process in your application. See the ScreenshotNeo 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

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.

FAQ

Should I set sourceScheme to Unset?

Usually, leave the optional property out. Use Unset only when you need its documented legacy protocol-client compatibility behavior. Puppeteer says it is temporary and slated for removal, but gives no date.

Does sourceScheme: 'Secure' set secure: true?

The references document these as separate properties and do not specify a universal mapping. Set and reason about each field according to its own meaning.

Why is the field Chrome-only?

Puppeteer’s CookieParam and CookieData references explicitly mark it as supported only in Chrome. The docs do not promise equivalent support in other browsers.

Which Puppeteer version should I use?

Use the version already required by your project and consult its matching API documentation. The inspected reference pages showed v25.11.0 for the type and v25.12.0 for the interfaces; those documentation versions do not guarantee what is installed in your environment.