Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
There is no single Docker flag that fixes every Puppeteer launch failure. First classify the error: a missing browser executable, missing Linux library, sandbox failure, unwritable profile or cache, or incompatible browser version. Then apply the fix for that layer; adding --no-sandbox blindly can remove an important security boundary without addressing the real cause.
Start by identifying which layer failed
Before changing the image or launch arguments, collect the details that distinguish a browser startup problem from a later automation failure. Puppeteer’s debugging guide documents dumpio: true as a way to forward Chrome’s stdout and stderr to the Node process, which can expose the actual startup error (Puppeteer debugging guide).
const browser = await puppeteer.launch({
dumpio: true,
});Use the complete exception and browser stderr to sort the failure into one of these categories:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →- Executable: Chrome was not downloaded, the configured path is wrong, or the file is not executable.
- Native libraries: Chrome starts but the operating system cannot load a required shared library.
- Sandbox: Chrome reports
No usable sandbox!or a related sandbox startup failure. - Writable paths: Chrome cannot create its profile, configuration, cache, or crashpad data.
- Compatibility: Puppeteer is being paired with an unvalidated system browser or mismatched browser build.
Record the exact Puppeteer version, base image and Linux distribution, CPU architecture, installation command and logs, configured executablePath, launch arguments, runtime user, and whether the filesystem is read-only. Those details matter because browser requirements and available sandbox capabilities depend on the runtime and image; consult Puppeteer’s system requirements and launch API for the release you run.
#1 Best Overall
Fix “Could not find Chrome” and executable-path errors
Puppeteer normally downloads a browser through its package installation process. If a package manager blocks install scripts, that download may never happen. Check the installation output and package-manager policy first; then allow the expected install script or deliberately manage the browser yourself.
Use a browser that exists in the final image
If you manage Chrome or Chromium separately, configure Puppeteer to use its real path with executablePath, or the documented PUPPETEER_EXECUTABLE_PATH environment override. Verify that the binary is present in the final image, not only in a build stage, and that the container’s runtime user can execute it.
const browser = await puppeteer.launch({
executablePath: process.env.PUPPETEER_EXECUTABLE_PATH,
});Do not assume a system-installed browser is interchangeable with Puppeteer’s downloaded browser. Puppeteer releases are paired with specific browser releases; the launch API says compatibility is guaranteed with the bundled browser. A separately managed browser may work, but validate that exact pairing rather than treating a successful installation as proof of protocol compatibility.
Fix missing shared libraries
If stderr names an unavailable .so file, inspect the browser’s dynamic dependencies inside the image. Puppeteer’s troubleshooting guide gives this example:
ldd /path/to/chrome | grep notInstall the missing package using the package manager for the image’s distribution, then rebuild and repeat the check. Debian and Ubuntu examples in Puppeteer’s guide include packages for NSS, GBM, GTK, X11, and font configuration; the exact set varies with browser build and base image, so do not paste a dependency list for a different distribution and assume it is complete. Consult the guide’s current Linux instructions and Chromium package lists for the browser and distribution you actually use (Puppeteer troubleshooting).
Requirements are version-sensitive. Puppeteer’s system requirements page currently lists Debian/Ubuntu x64 and arm64, and openSUSE/Fedora x64 and arm64 for Chrome for Testing. It lists Node.js 22.12 or later for Puppeteer 25.12.0. Treat those as version-specific requirements, not permanent rules: check the page for your installed Puppeteer release before changing Node or choosing an image (system requirements).
Resolve sandbox failures without discarding security
Chrome’s Linux sandbox helps isolate the host from web content. If Chrome prints No usable sandbox!, determine why the container or host cannot provide a usable sandbox. Puppeteer’s troubleshooting guidance says, “Running without a sandbox is strongly discouraged. Consider configuring a sandbox instead.” Its documented workaround with --no-sandbox is only appropriate when the content opened in Chrome is fully trusted; it should not be a routine Docker launch flag (Puppeteer troubleshooting).
Recommended Free Tools
For Puppeteer’s official Docker image
The official image is intended to run Chrome in sandbox mode, and its Docker guide requires the SYS_ADMIN capability. Its example is:
Rank #3
docker run -i --init --cap-add=SYS_ADMIN --rm
ghcr.io/puppeteer/puppeteer:latest
node -e "$(cat path/to/script.js)"That capability is broad. Confirm your Docker or orchestrator policy permits it and that the host meets the sandbox prerequisites; do not assume every managed runtime can grant it. Puppeteer’s guide documents the requirement and example at Puppeteer Docker guide. The guide’s latest tag is mutable, so pin a version-appropriate tag when repeatable builds matter.
For Ubuntu AppArmor and host-specific restrictions
Puppeteer’s troubleshooting material flags Ubuntu 23.10 and later AppArmor behavior as a possible reason Puppeteer-downloaded Chrome for Testing cannot use its sandbox. The correct remedy depends on host policy; follow the Chromium documentation linked from Puppeteer’s guide rather than disabling the sandbox or inventing a local policy workaround.
Fix crashpad, profile, cache, and read-only filesystem errors
Chrome writes configuration, cache, and profile data during startup. A read-only root filesystem or incorrectly owned mount can prevent those writes. One reported signature is chrome_crashpad_handler: --database is required. Puppeteer’s troubleshooting guide recommends directing XDG paths to writable locations, setting userDataDir to a writable directory, or mounting writable directories owned by the Chrome runtime user.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →const browser = await puppeteer.launch({
userDataDir: '/tmp/.puppeteer-profile',
env: {
...process.env,
XDG_CONFIG_HOME: '/tmp/.chromium/config',
XDG_CACHE_HOME: '/tmp/.chromium/cache',
},
});Adapt the paths to the container’s actual mounts and permissions. A conventional temporary path is not guaranteed writable in a hardened container. Check ownership as the user that launches Chrome, and ensure the parent directories exist or can be created. For a persistent profile mount, make the mounted directory writable by that same runtime user. See Puppeteer’s troubleshooting guidance for its read-only filesystem examples.
Use an init process and avoid orphaned browser processes
A container running Puppeteer should use an init process so child processes are managed properly. Puppeteer’s Docker example uses Docker’s --init; a custom entrypoint can provide an init process as well. This helps process cleanup and shutdown behavior, but will not repair a missing browser file, unavailable library, or bad executable path.
Choose between the official image and a custom image
| Choice | What it simplifies | What you must manage | Best fit |
|---|---|---|---|
| Puppeteer’s maintained Docker image | Includes Chrome for Testing, required dependencies, and a preinstalled Puppeteer version. | Accepting its base-image choices, pinning a suitable image tag, and meeting the documented sandbox capability requirement. | A lower-maintenance baseline when the runtime can provide the sandbox setup. |
| Custom image | Control over the base operating system and image construction. | Installing distro-specific libraries, keeping browser and Puppeteer versions compatible, making runtime paths writable, and providing process management. | Deployments with specific OS, size, policy, or dependency requirements and capacity to maintain them. |
For a custom image, start from Puppeteer’s official Dockerfile and adapt it to the chosen distribution and deployment constraints (Docker guide). Prefer a suitable non-root runtime user where feasible, verify browser and Puppeteer versions together, and explicitly provide writable profile/cache locations and an init process.
Be cautious with Alpine and less common base images
Puppeteer warns that Chrome does not support Alpine out of the box; compatible dependencies must be installed and tested. Its troubleshooting page also describes Chromium timing out on Alpine 3.20 in cited reports, with a downgrade to Alpine 3.19 resolving that issue in those reports. This is version-specific historical guidance, not a guarantee that every current browser build fails on Alpine 3.20 or succeeds on 3.19. For production, prefer a supported base image or carefully match the distribution’s Chromium build to the Puppeteer version, then test the exact image.
Trace a failure systematically
- Reproduce with diagnostics: enable
dumpio: trueand retain the full Node exception plus Chrome stderr. - Confirm the runtime: record Puppeteer version, Node version, distribution, architecture, container runtime, user, and read-only/mount settings.
- Check the binary: verify the configured executable exists in the final image and is executable by the runtime user.
- Check dynamic dependencies: run
ldd /path/to/chrome | grep notin the image and install missing distro packages. - Check sandbox policy: use the official image’s documented sandbox setup if possible; review host and runtime restrictions before changing security flags.
- Check writable paths: verify profile, XDG config/cache, and crashpad locations are writable and correctly owned.
- Check version pairing: use Puppeteer’s bundled browser or validate the exact system browser against the Puppeteer release.
For a precise diagnosis, the useful evidence is the entire launch error and stderr, install logs, Puppeteer version, image/distro and architecture, browser path, launch arguments, runtime identity and capabilities, and writable mount configuration. Without those details, matching the remedy to the observed error class is safer than trying random flags.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Or skip the browser setup
If your goal is to obtain a website screenshot rather than run a browser automation workload inside your own container, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try it without a card.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently asked questions
Does --init fix Chrome launch errors?
No. It helps manage browser child processes and shutdown behavior, but not missing binaries, shared libraries, sandbox prerequisites, or unwritable paths.
Can I use a system-installed Chrome with Puppeteer?
Yes, if you configure its executable path, but Puppeteer’s compatibility guarantee applies to its bundled browser. Validate a separately managed browser with your exact Puppeteer release.
Should I use --no-sandbox in CI?
Only when the content is fully trusted and the security implications are acceptable. Prefer a working sandbox configuration whenever the CI runtime permits it.
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.
