How to save and load cookies in Puppeteer
Cookies are how most sites remember that a browser has already signed in, accepted a consent banner or picked a region.
Puppeteer exposes that store through two page methods: one reads the current cookies, the other writes cookies back. This guide shows the read-then-write pattern, walks through a two-page example, and gives you a checklist for the common case where the cookies are restored but the page still behaves as if you were a new visitor.
The two methods that do all the work
Reading is handled by page.cookies(), which returns the cookies currently associated with the page. Writing is handled by page.setCookie(), which accepts cookie objects and installs them on the page. A save-and-load cycle is therefore just: call the read method, keep the returned array somewhere, and later pass those cookie objects to the write method.
One detail trips people up. page.setCookie() takes cookies as separate arguments, not as a single array, so the usual call spreads the saved array: page.setCookie(...cookies). If you pass the array without spreading it, you are handing the method one argument that is not a cookie object.
A two-page walkthrough
The example launches a browser, opens a new page and navigates to a first site. It then stores the result of page.cookies() in a variable called cookies. Next it navigates the same page to a second address, calls page.setCookie(...cookies) to install the saved cookies, reads the cookies again with page.cookies(), and prints them as JSON before closing the browser.
The printed output is the evidence that matters: it shows what the page actually holds after the write, not what you hoped to write. Treat that second read as your assertion step rather than an optional extra.
One caveat belongs to the example's shape rather than to Puppeteer. The first site and the second site are different origins, and a browser will not let one origin's cookies be applied as another origin's cookies. If the second read comes back without the cookies you passed in, origin mismatch is the first thing to check, not a bug in the method.
What a cookie object carries
Each entry returned by page.cookies() describes one cookie. When you plan to restore cookies later, these are the fields worth understanding:
- name and value: the pair the server reads. This is the part that usually carries the session.
- domain and path: the scope in which the browser will send the cookie. A cookie scoped to one host is not sent to a different host.
- expires: when the cookie stops being valid. A cookie with no expiry is a session cookie and disappears when the browser session ends.
- httpOnly: the cookie is hidden from page scripts but still sent with requests, which is typical for authentication cookies.
- secure: the cookie is only sent over HTTPS.
- sameSite: controls whether the cookie travels with cross-site requests.
When a restore appears to do nothing, compare these fields between what you saved and what the second read returns. A changed domain, an expired timestamp or a secure flag on a plain HTTP page will each produce a silent no-op rather than an error.
Checklist for a restore that does not stick
Work through these in order; each one rules out a different failure layer.
- Did the first read return anything? Log the length of the saved array before navigating away. An empty array means there was nothing to save, which is a capture problem, not a restore problem.
- Are the cookies scoped to the origin you are restoring into? Compare the domain field on each saved cookie with the host you navigate to next.
- Did you spread the array? Confirm the call reads page.setCookie(...cookies) and not page.setCookie(cookies).
- Did you read back after writing? A second page.cookies() call tells you whether the browser accepted the cookies.
- Has anything expired? Check the expires field against the current time before blaming the method.
- Is the page still logged out despite the cookies being present? That points at server-side session state, not at Puppeteer: the session may have been invalidated, or the site may require additional headers or tokens beyond the cookie.
Separating these layers matters because the fixes are completely different. Steps 1 to 5 are client-side and you can verify each one from the browser. Step 6 is outside the browser's control.
Keeping cookies beyond a single run
The array in the example lives only in memory. Close the process and it is gone, which is fine for a single script that saves and restores within one run but useless if you want a session to survive between runs.
The pattern is the same either way: capture with page.cookies(), serialize the array to storage you control, read it back on the next run, and pass the parsed objects to page.setCookie(). What changes is only where the array sits between the two steps. Two practical notes: store the serialized data somewhere private, because a session cookie is a credential; and expect the stored cookies to age, so a restore that worked last week can fail today purely on expiry.
Where this fits in a scraping workflow
Cookie handling is usually one step inside a larger Puppeteer script. If you are still assembling that script, the related questions cover loading local files, waiting for a page to finish loading, capturing background requests and responses, locating elements by CSS selector or XPath, and taking screenshots. Each of those is a separate concern from cookie transfer, and mixing them up is a common reason a script appears to fail at the cookie step when the real problem is a page that had not finished loading.
| Field | What it holds | Why it matters when loading |
|---|---|---|
| name | The cookie's identifier | Must match what the server expects; a renamed cookie is a different cookie |
| value | The stored string | Usually carries the session token |
| domain | Host scope | A cookie for one host is not applied to another host |
| path | URL path scope | Limits which requests carry the cookie |
| expires | Expiry timestamp | An expired cookie is discarded on write |
| httpOnly | Script visibility flag | Hidden from page scripts but still sent with requests |
| secure | HTTPS-only flag | Not sent over plain HTTP |
| sameSite | Cross-site send policy | Affects whether the cookie travels with cross-site requests |
Field meanings describe standard browser cookie attributes; the example itself only demonstrates reading and writing the array, not each field individually.
| Symptom | Layer | First check |
|---|---|---|
| Saved array is empty | Capture | Did page.cookies() run on a page that had cookies? |
| Cookies missing after write | Scope | Do the saved domains match the target host? |
| Write call throws or does nothing | Call form | Is the array spread into page.setCookie()? |
| Cookies present but session inactive | Server | Has the session been invalidated server-side? |
| Worked before, fails now | Time | Has the expires timestamp passed? |
Diagnostic ordering reflects how the two methods behave; it is not a substitute for inspecting the actual cookies in your script.
Frequently asked questions
Which Puppeteer methods save and load cookies?
page.cookies() returns the cookies for the current page, and page.setCookie() installs cookie objects onto the page. A save-and-load cycle is a read followed later by a write.
Why does page.setCookie(...cookies) use a spread operator?
Because page.setCookie() accepts cookies as separate arguments. Spreading the saved array passes each cookie object individually; passing the array directly hands the method a single argument that is not a cookie.
Can I copy cookies from one website to another?
Not across different origins. Cookies are scoped by domain, so a browser will not apply one site's cookies as another site's cookies. The two-page example works as a demonstration of the read and write calls, but a cross-origin restore will not carry a session.
Do saved cookies survive after the browser closes?
Only if you store them yourself. The array returned by page.cookies() exists in your script's memory, so serialize it to storage you control and read it back on the next run. Session cookies without an expiry also end with the browser session.
The cookies load but the page is still logged out. Why?
Once the cookies are present in the browser, the remaining variable is server-side: the session may have been invalidated, or the site may expect additional headers or tokens. Verify the cookie is actually present with a second page.cookies() call before looking further.