There is no single Docker flag that fixes every Puppeteer launch failure. Match the error to its layer: a missing browser executable, missing Linux library, unusable Chrome sandbox, unwritable profile or cache path, or a Puppeteer/browser version mismatch. Start by capturing the complete error and Chrome stderr; then apply the corresponding fix below. Avoid treating --no-sandbox as a default workaround because it removes an important browser security boundary.
Diagnose the launch failure before changing the image
A launch error is not always a browser launch error: Puppeteer can start Chrome and then fail later while connecting to it. Record enough detail to distinguish those cases before editing the Dockerfile.
- Enable browser output in the Puppeteer launch options with
dumpio: true. This forwards Chrome’s stdout and stderr to the Node process, helping identify failures such as a missing library or sandbox initialization problem. See the Puppeteer debugging guide. - Save the complete exception and stderr, not just the first line. Note the exact Puppeteer version, base image and Linux distribution, CPU architecture, package installation command and logs, configured browser path, launch arguments, runtime user, and whether the filesystem or particular mounts are read-only.
- Classify the evidence: missing browser or invalid path; missing shared library; sandbox or user-namespace failure; profile, cache, or crashpad write failure; or a browser/Puppeteer compatibility problem. The Puppeteer troubleshooting guide covers these Linux and Docker failure classes.
const browser = await puppeteer.launch({
dumpio: true,
// Keep your existing options while diagnosing.
});If Chrome’s output shows that it never became available, address that startup cause first. A later protocol or page-navigation error requires a different investigation.
Fix “Could not find Chrome” and invalid executable paths
Puppeteer normally downloads a browser during installation. If the package manager blocks install scripts, that download may not happen. Check the installation logs and package-manager policy, then allow the appropriate install step or deliberately provide a browser yourself.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- For a managed browser, set Puppeteer’s documented
executablePathlaunch option or thePUPPETEER_EXECUTABLE_PATHenvironment override. - Verify the browser exists in the final runtime image, not merely in a build stage, and that the container’s runtime user can execute it.
- Check that the path in the running container is the path actually passed to Puppeteer. A path on the host is not automatically present inside the container.
Keep Puppeteer and its intended browser release aligned. Puppeteer releases are paired with browser releases to preserve compatibility with Chrome DevTools Protocol and WebDriver BiDi; its launch API guarantees operation with the bundled browser, while a system browser is a compatibility choice to validate against the exact release. See the launch API and installation guide.
Fix missing Linux shared libraries
If stderr names a missing .so file, inspect the browser binary in the image and install the missing dependency using that distribution’s package manager. The troubleshooting guide suggests checking dependencies with ldd chrome | grep not; use the actual Chrome executable path in your container.
ldd /path/to/chrome | grep notDebian and Ubuntu images may need packages from categories including NSS, GBM, GTK, X11, and font configuration. The required set can change with the browser build and base distribution, so do not blindly copy a package list for a different image. Use the current dependency guidance linked from Puppeteer’s troubleshooting page, then rebuild and rerun the same launch command.
Check the requirements for the exact Puppeteer release too. The current system-requirements page lists Chrome for Testing support on Debian/Ubuntu x64 and arm64 and openSUSE/Fedora x64 and arm64; for Puppeteer 25.12.0 it lists Node 22.12 or newer. These are release-specific requirements, not a promise that every older or future release has the same matrix. Verify your installed release at Puppeteer system requirements.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Fix “No usable sandbox!” safely
Chrome’s Linux sandbox isolates browser content. If Chrome cannot establish a usable sandbox, it may fail with No usable sandbox!. First determine whether the host and container runtime support the sandbox configuration required by your deployment. Puppeteer strongly discourages running without a sandbox and describes --no-sandbox only for cases where the content opened in Chrome is fully trusted. It is a security trade-off, not a routine Docker fix.
Puppeteer’s official Docker image is intended to run Chrome in sandbox mode and requires the SYS_ADMIN capability. Its documented runtime pattern is:
docker run -i --init --cap-add=SYS_ADMIN --rm
ghcr.io/puppeteer/puppeteer:latest
node -e "$(cat path/to/script.js)"Use --init to provide an init process for managing browser child processes and shutdown behavior. The capability is broad; confirm it is permitted by your security policy and available in the actual Docker, CI, or orchestrator runtime. If the runtime cannot safely grant the sandbox prerequisites, resolve the deployment constraint rather than casually disabling Chrome’s sandbox. See the Puppeteer Docker guide.
The troubleshooting guide also identifies an AppArmor behavior on Ubuntu 23.10 and later that can affect Puppeteer-downloaded Chrome for Testing binaries. The appropriate remedy depends on host policy; follow the Chromium guidance referenced by Puppeteer rather than improvising by disabling sandboxing. See Puppeteer troubleshooting.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Fix crashpad, profile, cache, and read-only filesystem errors
Chrome writes configuration, cache, and profile data during startup. In a read-only container, or one where only selected mounts are writable, startup can fail with errors such as chrome_crashpad_handler: --database is required.
- Identify which paths the container can actually write to. Do not assume
/tmpis writable; inspect the image and runtime mounts. - Point XDG configuration and cache paths to writable locations, for example
/tmp/.chromium, as described in Puppeteer’s troubleshooting guidance. - Set Puppeteer’s
userDataDirto a writable location such as/tmp/.puppeteer-profile, or mount a writable profile directory. - For mounted directories, ensure ownership and permissions allow the Chrome runtime user to write. Recheck them after a container restart or deployment change.
If you use a read-only root filesystem, explicitly provide writable mounts for the paths Chrome needs and configure the browser to use them. A profile directory that is writable during image build can still be inaccessible to the different user running the container.
Check Alpine and less common base images
Chrome does not support Alpine out of the box; compatible dependencies and the selected browser must be installed and tested together. Puppeteer’s troubleshooting page includes a version-specific report of Chromium timing out on Alpine 3.20 and a resolution by downgrading to Alpine 3.19. That report is historical and does not establish a permanent rule for every current browser build.
For production, prefer a supported base image where practical. If Alpine or another less common image is required, match its distribution packages and Chromium version to the Puppeteer version, then test the exact final image and runtime configuration rather than assuming a successful build means Chrome can launch.
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 →Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Choose the official image or maintain a custom image
The official Puppeteer image provides a lower-maintenance starting point with Chrome for Testing, required dependencies, and a preinstalled Puppeteer version. The example above uses the mutable latest tag; pin a version-appropriate image tag when reproducible builds matter. The Docker guide lists tags by Puppeteer version.
A custom image gives you control over the base operating system, but makes you responsible for dependency installation, browser/Puppeteer compatibility, writable paths, runtime user, sandbox capability, and update policy.
| Decision factor | Official Puppeteer image | Custom image |
|---|---|---|
| Browser dependencies | Chrome for Testing and required dependencies are included. | You install and maintain dependencies for the selected distribution. |
| Base OS control | Less control over the base image. | More control over base image and system packages. |
| Version management | Choose and pin an appropriate Puppeteer image tag. | You coordinate browser and Puppeteer versions yourself. |
| Sandbox and runtime | The documented sandboxed setup requires SYS_ADMIN. |
You configure and validate sandbox requirements for your environment. |
| Writable paths and user | Still verify runtime permissions and mounts. | Configure ownership and writable paths as part of the image and deployment. |
| Updates | Adopt updated image tags deliberately. | Maintain OS, libraries, browser, and Puppeteer updates yourself. |
Whichever route you choose, pin the versions that matter, run a smoke test in the deployed container, and revisit the browser and operating-system dependencies when upgrading Puppeteer.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is to produce website screenshots rather than operate Chrome inside your own container, ScreenshotNeo offers a screenshot API and MCP server. Its browser setup handles cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. AI agents can use its MCP server, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
One GET request can return an image or PDF. For example, this cURL request saves a WebP screenshot:
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpSee the ScreenshotNeo API documentation for request options, formats, and response details. Sign up for the free plan to get 1,000 screenshots a month with no card.
Common follow-up failures
- It works locally but fails in Docker: Compare the host and container browser paths, Linux distribution, architecture, installed libraries, user, and writable mounts. The container is the environment that must contain the executable and its dependencies.
- The image builds but launch still fails: Run the test as the production runtime user and with the production capabilities and filesystem mounts. Build-time permissions do not prove runtime access.
- Adding
--initchanges nothing: Init helps manage child processes; it does not install Chrome, supply libraries, make a path writable, or configure the sandbox. - A system Chrome starts but behaves unpredictably: Validate it against the installed Puppeteer release. The bundled browser is the supported compatibility baseline.
- The error persists after a fix: Re-enable or retain
dumpio: true, capture fresh stderr from the final image, and reclassify the failure. One change may expose the next missing prerequisite.
A precise diagnosis depends on the complete launch error and stderr, Puppeteer version, image and architecture, runtime and capabilities, user, launch options, browser path, install logs, and writable mounts. Without those details, choose a fix from the observed error class instead of applying a random dependency list or disabling the sandbox.
Frequently Asked Questions
Does Puppeteer’s Docker image run with Chrome sandboxing enabled?
Yes. The official image guide describes the image as intended for sandbox-mode execution and documents the required runtime capability.
Free tools Windows power users keep installed
One-click scans. No signup required.
Can I use a system-installed Chrome instead of Puppeteer’s downloaded browser?
You can configure an executable path, but compatibility with a system browser should be validated against your exact Puppeteer release.
Is Alpine always incompatible with Puppeteer?
No universal conclusion follows from the version-specific warning. Chrome is not supported on Alpine out of the box, so dependencies and browser versions need to be matched and tested.
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.
