In Puppeteer, a cookie’s optional sameSite value is Strict, Lax, or None. The setting tells Chromium when it may send that cookie with requests; it does not change the cookie’s domain or path. For cross-site use, Chromium requires SameSite=None; Secure. For new Puppeteer code, use Browser.setCookie() or BrowserContext.setCookie(), not the obsolete Page.setCookie() API.
What the SameSite values mean
SameSite is a browser cookie policy, not a Puppeteer-specific behavior. Puppeteer lets you set the cookie attribute; Chromium decides whether the cookie accompanies a particular request. The request’s site context, navigation type, and HTTP method all matter.
As an Amazon Associate I earn from qualifying purchases.
| Value | When Chromium may send the cookie | When it fits |
|---|---|---|
Strict |
With same-site requests only. | When a cross-site entry should not carry the cookie. |
Lax |
With same-site requests and cross-site top-level navigations using a safe HTTP method. | When first-party use is intended but common safe navigation into the site should still work. |
None |
With same-site and cross-site requests, subject to browser requirements. Chromium requires the cookie to also be Secure. |
When the cookie genuinely needs to work in a third-party or other cross-site context and secure transport is in place. |
Chromium advises using Lax or Strict for cookies needed only in a first-party context, and None; Secure for cookies needed in a third-party context. See Chromium’s SameSite guidance.
What happens if you omit sameSite?
Chromium’s documented default for a cookie with no SameSite attribute is Lax. That means omission does not mean “send this cookie everywhere”: cross-site requests can still omit it, including flows where a developer expected third-party behavior. If cross-site delivery is required, set sameSite: 'None' and secure: true, then test the actual request in the target browser.
#1 Best Overall
Set a cookie with a current Puppeteer API
Puppeteer’s documented CookieData type includes optional sameSite and secure properties. The current documentation identifies itself as version 25.12.0. Set the cookie through the browser or browser context; Puppeteer marks Page.setCookie() obsolete and directs users to Browser.setCookie() or BrowserContext.setCookie().
Browser-context example
const browser = await puppeteer.launch();
const context = browser.defaultBrowserContext();
await context.setCookie({
name: 'session',
value: 'example-session-value',
domain: 'example.com',
path: '/',
sameSite: 'None',
secure: true,
});
const page = await context.newPage();
await page.goto('https://example.com');
await browser.close();Replace the example domain, cookie name, and value with those used by your application. Use sameSite: 'Strict' or sameSite: 'Lax' when those policies match the intended flow; do not choose None merely to work around a debugging symptom. The API fields configure the cookie, but do not override Chromium’s acceptance or sending rules. Refer to the Puppeteer CookieData API and the obsolete Page.setCookie API notice.
Choose a value based on the request flow
Same-site request
All three values can be sent with same-site requests, assuming the cookie otherwise matches the request’s domain and path and is accepted by the browser.
Recommended Free Tools
Cross-site top-level navigation
Lax permits the cookie on a cross-site top-level navigation when it uses a safe HTTP method. Strict does not permit that cross-site use. If the flow depends on a cross-site navigation that does not meet the Lax conditions, do not assume Lax will work.
Rank #3
Embedded content, other cross-site requests, and POST flows
Strict and Lax do not provide the general cross-site behavior of None. If an embedded or other cross-site request must carry the cookie, use SameSite=None; Secure where appropriate and verify the exact flow. A cross-site POST is not equivalent to a safe top-level navigation: test it directly rather than relying on historical browser exceptions.
How to tell whether a cookie is affected
- Check the cookie attributes. Confirm the browser stored the intended domain, path, SameSite value, and Secure setting. Puppeteer’s
CookieDatainterface exposes the relevant fields. - Inspect browser storage. In DevTools, open the Application storage view and inspect the cookie’s attributes. Chromium also describes Console warnings for affected cross-site requests.
- Inspect the actual request. In DevTools Network, select the request that should include the cookie and check whether it was sent and whether the browser reports a reason it was excluded.
- Reproduce the same context. Test the real entry point and request type: same-site navigation, cross-site top-level navigation, embedded request, or cross-site POST. Changing the request context can change whether a cookie is eligible.
Chromium’s SameSite FAQ describes these browser checks and the cross-site None; Secure requirement.
Common problems and fixes
- A cross-site request does not include the cookie: Check whether it is
LaxorStrict, whether the request is a qualifying safe top-level navigation, and whether the cookie’s domain and path match. If the use genuinely requires cross-site delivery, configureNonewithSecure. SameSite=Nonestill does not work: Confirm thatsecure: trueis set and that the test uses the actual secure deployment and request context.Nonealone does not guarantee delivery.- The cookie is not stored or does not match the target: Inspect the stored cookie’s domain and path in DevTools, along with SameSite and Secure. Correct the attributes for the host and route that need the cookie.
- A cross-site POST behaves differently from a GET navigation: They are different request cases under the Lax rules. Reproduce the POST directly in the target browser; do not rely on an old temporary Lax+POST exception.
- Code uses
page.setCookie(): Replace it withbrowser.setCookie()orbrowserContext.setCookie(), as appropriate for the context in which the cookie should be available.
Which historical testing advice still applies?
Chromium’s rollout page is historical, not a current testing recipe: it records removal of relevant chrome://flags controls as of Chrome 91, planned removal of a command-line flag in Chrome 94, and a latest update date of 2021-03-18. The older testing page also describes a temporary Lax+POST exception. Do not use those rollout milestones or the temporary exception as a promise about current Chrome behavior. Test the browser and timing-sensitive flow you actually support. See Chromium’s rollout information and its older testing guidance.
Or skip the browser setup
If you need a clean screenshot of a page while debugging a web flow, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Its capture can accept cookie and consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status in headers. The MCP tools include take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo documentation. Example cURL request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpThe Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
