Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If page.setCookie() appears to do nothing, check five things first: await the coroutine, give the cookie a valid URL or domain/path, avoid running it on about:blank or a data: page, read it back for the same URL, and inspect the same browser context. The following diagnostic flow is based on Pyppeteer’s documented API and page implementation; exact behavior can differ between installed releases.
Use an awaited, scoped cookie call
Page.setCookie is asynchronous. Calling it without await creates a coroutine but does not send the browser-protocol command. Put the call inside an async def function and await it before navigating or checking state.
import asyncio
from pyppeteer import launch
async def main():
browser = await launch(headless=True)
page = await browser.newPage()
await page.goto("https://example.com/", {"waitUntil": "networkidle2"})
await page.setCookie({
"name": "session_hint",
"value": "example",
"url": "https://example.com/",
"path": "/",
"secure": True,
"sameSite": "Lax",
})
cookies = await page.cookies("https://example.com/")
print(cookies)
await browser.close()
asyncio.get_event_loop().run_until_complete(main())The required fields are name and value. A URL is usually the least ambiguous scope. The API also accepts documented cookie properties such as domain, path, Unix-seconds expires, httpOnly, secure, and sameSite. Use the spelling and value format expected by the Pyppeteer release you installed.
Fix the page URL before calling setCookie
When no cookie URL is supplied, Pyppeteer can infer one from the current page only when that page URL is an HTTP origin. A new page normally starts at about:blank; a data URL is also unusable for this purpose. The development-branch implementation explicitly rejects those cases.
#1 Best Overall
Navigate first
await page.goto("https://app.example.com/login")
await page.setCookie({
"name": "experiment",
"value": "control",
"path": "/",
})Or specify the intended URL
await page.setCookie({
"name": "experiment",
"value": "control",
"url": "https://app.example.com/",
"path": "/",
})Do not use a cookie URL that conflicts with its security attributes. For example, a secure cookie is intended for HTTPS requests. A host-only cookie scoped to app.example.com will not appear on www.example.com, and a path such as /account does not apply to unrelated paths.
Verify the cookie against the origin it affects
await page.cookies() returns cookies for the current page URL. Supplying one or more URLs filters the result to cookies that affect those URLs. Therefore, a successful set can look like a failure if you inspect another host, scheme, or path.
print("Current page:", page.url)
print("For app origin:", await page.cookies("https://app.example.com/"))
print("For a different host:", await page.cookies("https://www.example.com/"))Compare the returned dictionary’s name, value, domain, path, secure, sameSite, and expiry fields with what you requested. Then make the request or navigation that should consume the cookie and inspect the actual request or application behavior. A cookie can exist in the browser store yet be excluded from a particular request because its domain, path, scheme, SameSite policy, or expiry does not match.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use the same page and browser context
A BrowserContext is an independent browser session. Cookies set in one context are not automatically available in another. The same issue occurs when code sets a cookie on one page and later checks a newly created page belonging to a different context or browser instance.
context = await browser.createIncognitoBrowserContext()
page = await context.newPage()
await page.goto("https://example.com/")
await page.setCookie({
"name": "context_test",
"value": "1",
"url": "https://example.com/",
})
# Verify on a page created by this same context.
check = await context.newPage()
await check.goto("https://example.com/")
print(await check.cookies("https://example.com/"))When debugging, log the browser object, context, page identity, and page.url at both the set and read points. Also check that cleanup code has not closed the browser and that a later navigation or test fixture has not created an isolated session.
A minimal diagnostic sequence
- Capture the complete exception and print
page.urlimmediately beforesetCookie. - Confirm the function containing the call is asynchronous and the call is written as
await page.setCookie(...). - Navigate to the target HTTP(S) origin, or provide an explicit
url. - Start with only
name,value,url, andpath; add security and expiry attributes after the basic case works. - Read back with
await page.cookies(the_exact_URL), not an unrelated URL. - Check the same page, browser, and context, then perform the request that should carry the cookie.
- If it still fails, record Python, Pyppeteer, and Chrome/Chromium versions and reduce the program to one page and one cookie.
Cookie scope details that commonly cause confusion
url versus domain
A URL ties the cookie to a concrete origin and is convenient for diagnostics. A domain cookie can intentionally cover subdomains, but the leading-dot and host rules are enforced by the browser. Do not assume a cookie for a parent domain will be sent to every unrelated hostname.
path
The default or chosen path limits where the cookie is sent. Use / for an application-wide cookie only when that is the legitimate scope; otherwise set the narrow path required by the site.
expires and session lifetime
expires uses Unix seconds. A past timestamp can immediately remove the cookie, while an omitted expiry creates a session cookie. Check the value returned by cookies() rather than assuming the browser interpreted a local-date string.
secure and sameSite
secure limits transmission to HTTPS. SameSite behavior controls cross-site requests and can prevent a cookie from appearing in a flow even though it is stored. Test the real navigation sequence, not just the cookie store.
HTTP-only cookies
An httpOnly cookie is intended to be inaccessible to page JavaScript. That does not mean it is absent: inspect it through Pyppeteer’s cookie API or browser network tooling.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
RuntimeWarning: coroutine ... was never awaited |
The asynchronous method was called like a normal function. | Use await page.setCookie(...) inside the running event loop. |
Page error mentioning about:blank or data: |
No usable HTTP origin was available for URL inference. | Navigate to the target origin first or pass an explicit cookie url. |
| Cookie list is empty for a check URL | The filter URL does not match the cookie’s domain, path, or scheme. | Call page.cookies() on the current page and then test the exact intended URL. |
| Cookie appears on one page but not another | Different browser context or browser instance. | Keep both pages in the same context, or set the cookie again in the intended context. |
| Cookie is stored but not sent | Secure, SameSite, path, domain, expiry, or navigation rules exclude the request. | Inspect the returned attributes and the request’s actual URL and method. |
| Protocol or launch failure before cookie code | Environment or browser compatibility issue. | Record versions, verify the Chrome/Chromium executable, and reproduce with a minimal script. |
Versions, installation, and reproducibility
The Pyppeteer README states that “pyppeteer requires Python >= 3.8.” On first use, Pyppeteer may download Chromium if it cannot find a suitable Chrome binary. Pin the package and browser environment used by your project, and include the exact traceback in a bug report. The available documentation does not establish a universal, current cookie-specific compatibility bug, so version details matter.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →python --version
python -m pip show pyppeteer
# Also print the browser version from your launched Chromium/Chrome.Behavior in the development branch can differ from older releases. Consult the Page.setCookie implementation, the 0.0.25 API reference, and the project README for the release you actually run.
Or skip the browser setup
If your goal is a clean image of a page rather than maintaining browser-cookie state, ScreenshotNeo provides a GET endpoint and an MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in X-Page-Verdict and X-Billed headers. AI agents can use its MCP tools take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for authentication and options. A one-call cURL capture is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython and Node.js clients are equally simple:
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}`);The Free plan includes 1,000 screenshots each month without a card. Paid plans start at $5 for 3,000 screenshots; every feature is included on every plan. Sign up free for ScreenshotNeo.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsWhen to ask for more evidence
If the minimal script still fails, preserve the cookie payload with secrets removed, the exact target URL, the traceback, and Python, Pyppeteer, and browser versions. That information distinguishes a scope mistake from an environment-specific protocol problem without assuming that every report has the same cause.
Frequently Asked Questions
Can I set a cookie before calling page.goto()?
Yes, but provide an explicit HTTP(S) url. Relying on URL inference while the page is about:blank or a data: URL is rejected by the implementation described above.
Why does DevTools show no cookie even though page.cookies() returns one?
Check that DevTools is displaying the same browser context and exact host/path, and remember that httpOnly cookies are not available to page JavaScript.
Does Pyppeteer support the same cookie fields as Puppeteer?
Pyppeteer’s API documents URL, domain, path, expiry, HttpOnly, secure, session, and SameSite-related fields, but validate names and accepted values against the version installed in your project.
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.
