Most Playwright persistent-context failures in Docker come from one of four causes: two browser processes using the same profile directory, automation targeting Chrome’s normal profile, a mismatch between the Playwright package and container image, or container settings that let Chromium run out of resources. Use a dedicated writable profile for each process, pin matching versions, start the container with --init and (for Chromium) --ipc=host, and collect DEBUG=pw:browser logs before changing sandbox or display settings.
What a persistent context changes
browserType.launchPersistentContext(userDataDir, options) starts a browser whose cookies, local storage and other session data live in userDataDir. The call returns the browser’s only context; closing that context also closes the browser, as documented in the BrowserType API.
A profile directory is a lockable browser resource, not a generic cache. Playwright does not support launching multiple browser processes against the same directory. Give every concurrent worker its own path and close the context before reusing a path.
Use an automation-only, writable profile
Do not point at Chrome’s everyday profile
Recent Chrome policy changes make automating the default profile unsupported. Playwright’s code-generation documentation calls out Chrome 136 and later: create a separate user-data directory instead of accessing the normal Chrome profile. This cutoff is Chrome-specific; do not apply it as a rule for Firefox or WebKit.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Never mount a developer’s live profile into a container. It may be locked by another Chrome process, contain extensions or policies that alter startup, and expose personal credentials to the test. Create an empty directory owned by the container user, or a unique temporary directory per job.
Minimal Node.js example
import { chromium } from 'playwright';
const profile = process.env.PROFILE_DIR || '/tmp/pw-profiles/job-1';
const context = await chromium.launchPersistentContext(profile, {
headless: true,
});
try {
const page = await context.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
} finally {
await context.close(); // closes the browser too
}For parallel jobs, set PROFILE_DIR to a different directory for each worker, such as /tmp/pw-profiles/job-${WORKER_ID}. If a previous run died, remove or archive that job’s directory only after confirming no browser process still uses it.
Align the Playwright package and Docker image
The project’s Playwright dependency must match the version in the container. The official image includes browser binaries and system dependencies, but it does not install your project’s package for you. A mismatch can make Playwright search for an executable that is absent from the image.
Pin both sides rather than using a floating tag. For example, keep the image tag and the npm dependency on the same release line, then update them together. The exact image tags shown in Playwright’s Docker documentation evolve, so check the current tag when you update your lockfile.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFROM mcr.microsoft.com/playwright:v<PLAYWRIGHT_VERSION>-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "run.js"]Replace <PLAYWRIGHT_VERSION> with the pinned version used in package.json. Rebuild after every version change; an old image layer can otherwise leave stale browser binaries behind.
Rank #2
- 【Build Your Own NAS & Homelab — Not Just Storage】 More than a traditional NAS, ZimaBlade 7700 is a flexible x86 mini server for building your own homelab, personal cloud, or Docker host. Perfect for DIY NAS, self-hosting, container apps, and even retro systems — not limited like typical ARM-based NAS devices.
- 【x86 Platform — Broad Compatibility, Real Freedom】 Powered by an Intel quad-core x86 processor, it runs a wide range of operating systems and software with native compatibility. Ideal for Linux, Docker, CasaOS, and more — designed for flexibility and experimentation rather than locked-down appliance use.
- 【16GB RAM for Smooth Multi-Service Workloads】 Handle file sharing, media streaming, backups, and multiple lightweight services at once. Optimized for low-power, always-on operation — a great fit for home labs and personal servers running 24/7.
- 【Smooth 4K Media Streaming — Plex Direct Play Ready】 Stream your personal media library smoothly with Plex and similar media servers. Supports 4K playback on compatible devices via direct play, delivering a reliable home media experience without the need for heavy transcoding.
- 【Complete 2-Bay NAS Kit — Ready to Build】 Includes power supply, 16GB RAM, metal drive cage for 2 HDD/SSD, and dual SATA cables — everything you need to start building your own NAS right out of the box.
Start Docker with browser-friendly process settings
Use an init process
Playwright recommends Docker’s --init option so PID 1 reaps child processes and does not leave zombies after browser crashes:
docker run --rm --init
--ipc=host
-e DEBUG=pw:browser
-v "$PWD:/app"
-w /app
my-playwright-imageGive Chromium adequate shared memory
For Chromium, Playwright recommends --ipc=host. Without it, Chromium can exhaust the container’s shared-memory area and crash. This is a general Chromium stability recommendation, not a guarantee that a profile-lock problem will disappear.
If host IPC is unacceptable in your environment, explicitly size shared memory and monitor crashes, for example with --shm-size=1g. Choose a value appropriate to your workload and security policy; the documentation’s recommendation is host IPC.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Treat extra capabilities as diagnostics
The Docker guide mentions --cap-add=SYS_ADMIN as a local-development diagnostic for unusual Chromium launch errors. Do not add it by default to production containers. First capture logs, verify permissions and versions, and fix the underlying configuration.
Choose the sandbox and Linux user deliberately
The documented Playwright image runs as root by default, which disables Chromium’s sandbox. Root can be acceptable for trusted end-to-end tests, but it is a poor default for browsing untrusted sites.
Trusted test workloads
Keep the image’s documented root setup only when the pages and test code are trusted, and restrict network and container permissions as usual. Do not present root as a universal solution to launch failures.
Scraping or untrusted browsing
Create a non-root user and use the seccomp profile supplied by Playwright’s Docker guidance so Chromium can use user namespaces while retaining its sandbox. Ensure that user owns the profile directory and can write to it. A profile mounted read-only, or owned by root while the browser runs as another user, commonly produces immediate exits or permission errors.
Headless versus headed execution
Headless mode is Playwright’s default and needs no visible display. If you request headed Linux execution (for example, headless: false), an X server is required. Playwright’s CI documentation states that headed Linux execution requires Xvfb and shows xvfb-run as the prefix:
xvfb-run --auto-servernum node run.jsThe Playwright Docker image and GitHub Action include Xvfb. In a custom image, install it yourself and verify that DISPLAY is set by xvfb-run. A missing display usually reports a display or X-connection error rather than a profile error.
Run a repeatable diagnostic sequence
- Record the exact failure. Save the container command, Playwright package version, image tag, browser engine, launch options and the complete stderr output.
- Enable browser logs. Run with
DEBUG=pw:browser, the launch-failure setting documented by Playwright. For verbose API call tracing, addDEBUG=pw:apiwhen needed. - Prove the profile is unique. Print the resolved
userDataDir, check whether another container or process uses it, and test with a new empty directory. - Check write access. Inside the container, run
id, inspect the directory owner and permissions, and create a file there as the browser user. - Verify versions. Compare
npm ls playwright(or the equivalent package manager output) with the image tag. Rebuild the image after changing either one. - Test headless mode. If headless works but headed mode fails, add Xvfb rather than changing the profile.
- Apply runtime settings. Add
--initand, for Chromium,--ipc=host. Only then investigate memory limits, custom seccomp rules or capabilities. - Retest one variable at a time. Keep the successful minimal command, then reintroduce cookies, mounted profiles, custom arguments and concurrency individually.
Common symptoms, causes and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| “Failed to launch browser” with an executable-not-found message | Package and image versions do not match, or browsers were never installed in a custom image | Pin matching versions; use the official image or install the matching browsers and dependencies. |
| Browser exits immediately when using a familiar Chrome profile | Default profile is locked or unsupported by current Chrome policy | Create a separate automation profile; do not target the normal profile (Chrome 136+ explicitly documents this restriction). |
| “Opening in existing browser session” or profile-lock errors | Another process uses the same userDataDir |
Stop the old process, close the persistent context, and assign a unique directory per concurrent process. |
| Permission denied while creating profile files | Mounted directory is read-only or owned by a different container user | Use a writable volume and matching ownership, or choose a container-local directory. |
| Random Chromium crashes or “out of memory” messages | Small container shared-memory area or tight memory limit | Use --ipc=host as Playwright recommends, or size shared memory and container memory for the workload. |
| Headed launch reports no display or X connection | X server is absent | Run headless, or install/use Xvfb with xvfb-run. |
| Only untrusted sites fail under a hardened container | Sandbox, user, seccomp or namespace policy prevents Chromium startup | Run as a non-root user and apply Playwright’s documented seccomp approach; do not disable the sandbox blindly. |
Persistent profiles in CI and production
Persist only what you need
A persistent directory is useful when a workflow must retain cookies or local storage between runs. In CI, ephemeral per-job directories reduce lock contention and prevent credentials from leaking between tests. If you persist a volume, define ownership, cleanup and retention explicitly; browser profiles can contain authentication material.
Rank #4
- Dell PowerEdge R730xd 24B SFF 2U Server
- 2x Intel Xeon E5-2690 v4 2.6Ghz 14-Core (28-cores Total)
- 128GB DDR4 RAM – 4x 1.2TB 10K SAS 2.5” 12Gb/s
- Dell H730P mini 2GB 12Gb/s RAID
- 2x 750W PSU - 2x 10Gb SFP+ 2x 1Gb (RJ45) NIC
Control concurrency
Map each worker to one profile path. A queue can reuse a path only after the previous context has closed. Do not rely on random suffixes without recording them, because cleanup becomes difficult after interrupted jobs.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsSeparate browser stability from page behavior
Timeouts, bot checks and application crashes can look like launch failures if logging is incomplete. First establish that a blank, headless page opens with a fresh profile; then add authentication state, custom arguments and target URLs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server when you need an image or PDF rather than a stateful browser session. Its request accepts a URL and returns PNG, JPEG, WebP or PDF. The API can accept cookies, headers, user agents, JavaScript, waits, selectors, device settings and other capture options; an MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
One-call example (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Before capture, ScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status. Free usage is 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create an account at ScreenshotNeo’s free sign-up.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Frequently asked questions
Can two Playwright browsers share one user-data directory?
No. Use a distinct directory for every simultaneous browser process and wait for the previous context to close before reusing one.
Best Value
- Ateco #1357 Dough Docker for use with pastry or pizza dough for best baked results
- Roll over pizza dough, pie dough, pastries before baking, the small depressions help reduce blistering or air pockets from forming while crust bakes
- Measures 5.25-Inches wide, 2.25-Inch diameter, 8.25-Inches long including handle
- Hand wash suggested for best results; made from high impact plastic
- Family owned and operated since 1905, Ateco has produced specialized professional quality baking and decorating tools for professional pastry chefs and discerning home bakers alike
Does closing a page release the persistent profile?
No. Close the persistent context. It is the operation that closes the browser and releases the profile lock.
Do Firefox and WebKit have the Chrome 136 profile restriction?
The cited restriction is specific to Chrome’s default profile. Use separate automation directories for every engine, but do not generalize that Chrome version cutoff to Firefox or WebKit.
Frequently Asked Questions
Can I copy a persistent profile between containers?
Only if the destination browser and Playwright versions, filesystem ownership and profile format are compatible. For isolated CI jobs, a fresh profile per job is safer than copying a live directory.
Should I add --no-sandbox to make Docker launch?
Not as a blanket fix. Root already disables Chromium’s sandbox in the documented image; for untrusted browsing, use a non-root user and the documented seccomp configuration instead.
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.
