Recommended Free Tools
“No usable sandbox!” means Chrome could not find a usable Linux sandbox in its execution environment. It does not, by itself, mean Puppeteer is missing. The safest fix is to configure Docker and the host so Chrome can run with its sandbox enabled—not to make --no-sandbox the default. Puppeteer’s troubleshooting guide says, “Running without a sandbox is strongly discouraged.”
Start with Puppeteer’s official Docker image if it fits your deployment. For a custom image, check sandbox prerequisites, the user Chrome runs as, shared libraries, writable profile and cache paths, process cleanup, and host AppArmor policy. These are separate failure classes: a missing library or unwritable profile can stop Chrome too, but they are not the same diagnosis as a missing sandbox.
What “No usable sandbox!” means
Chrome uses multiple sandbox layers to isolate browser processes from web content. The error means Chrome could not use a supported sandbox in the environment where it started. Puppeteer identifies the error in its troubleshooting documentation; the message alone does not establish that the Puppeteer package or browser binary is absent.
Docker does not automatically solve the host’s sandbox requirements. Chrome still depends on the container runtime, host policy, user configuration, and filesystem being suitable for the sandbox mechanism it is trying to use. Conversely, not every Chrome startup failure is a sandbox failure: missing shared libraries and read-only browser directories can produce different errors.
#1 Best Overall
Fastest supported fix: use Puppeteer’s Docker image
Puppeteer’s official image includes Chrome for Testing, required dependencies, and a pre-installed Puppeteer version. It is intended to run Chrome in sandbox mode. Its documented Docker invocation uses both --cap-add=SYS_ADMIN and --init:
docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "$(cat path/to/script.js)"Replace path/to/script.js with the path to your script in the environment from which the command runs. The example grants a Linux capability to the container, so do not add it casually: use the documented configuration that matches your deployment and review the security implications with your platform’s administrator. The official guide explains why this capability is required for its sandbox configuration, and why an init process helps manage processes started by Puppeteer: Puppeteer’s Docker guide.
Pin a version for repeatable deployments
The Docker guide displayed Puppeteer version 25.12.0 when accessed on September 29, 2026. Its example uses the mutable latest tag, which can point to a different image over time. For reproducible builds, select a versioned image tag that matches the Puppeteer version you intend to run, and verify the current tag and instructions in the official guide before deploying. Do not assume a tag remains current or that a newer image is interchangeable with an older application setup.
Rank #2
When you build your own image
If the official image is not suitable, Puppeteer’s Docker documentation points to its Dockerfile as a starting point for a different base image. Adapt the dependencies, user setup, paths, and runtime configuration to your actual distribution and deployment rather than copying an old Dockerfile unchanged.
Free tools Windows power users keep installed
One-click scans. No signup required.
Fix a custom Docker image step by step
-
Confirm host and sandbox prerequisites
Check that the Docker runtime and host security policy permit the sandbox mechanism Chrome needs. The official image’s documented setup includes
--cap-add=SYS_ADMIN; that is evidence for that documented configuration, not a blanket instruction to grant extra capabilities to every container. Confirm the appropriate setting for your image and deployment before changing permissions. -
Run Chrome as a non-privileged user
Puppeteer’s troubleshooting example creates a user named
pptruserand switches to it. The example’s comments explain that this avoids needing--no-sandbox. In your image, make sure the selected user owns or can access the application files and browser directories it needs. Adjust usernames and paths to your image rather than assuming the example’s ownership and directory layout match yours. -
Check Chrome’s shared libraries
A browser binary can be present and still fail to start if required system libraries are missing. Puppeteer recommends checking unresolved dependencies with:
ldd chrome | grep notRun this against the Chrome binary used by your container, with the appropriate path for your image. Puppeteer’s troubleshooting guide provides Debian and CentOS package lists as examples, but cautions that package needs vary and lists may become outdated. Use the current Chrome installer dependency list for the distribution and Chrome build in your image; do not treat an example list as universal.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Make the profile, configuration, and cache writable
In a read-only container, Chrome still needs writable locations for browser data. Puppeteer documents setting
XDG_CONFIG_HOMEandXDG_CACHE_HOMEto writable locations such as/tmp, setting Puppeteer’suserDataDirto a writable path, or mounting writable volumes owned by the Chrome user.For example, set the environment paths in the image or container to directories the running user can write. If you use a mounted volume, verify ownership and permissions from inside the container, not just on the host. A startup message such as
chrome_crashpad_handler: --database is requiredmay indicate a writable-path problem rather than a sandbox failure. -
Ensure Chrome child processes are reaped
Use Docker’s
--initoption, as in Puppeteer’s official invocation, or provide a custom init entrypoint. Puppeteer can start child processes; an init process helps manage their lifecycle, especially when the container stops or restarts. -
Investigate AppArmor only when the host matches
Puppeteer documents a specific case on Ubuntu 23.10 and later: an AppArmor profile for Chrome stable may prevent Puppeteer-downloaded Chrome for Testing from using user namespaces, resulting in the same error. This is a host-policy issue, not a universal explanation for Docker failures. Check the host’s actual profile and follow the linked Chromium policy guidance before applying any workaround. Verify that the Ubuntu version, Chrome build, and installation method match the documented case.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Best Value
Docker Container Linux Devops Programming Coding T-Shirt- 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
Choose between enabling the sandbox and disabling it
| Approach | When it fits | Security and operational trade-off |
|---|---|---|
| Configure Chrome sandbox support in the official Puppeteer image or a correctly prepared custom image | Preferred when the host and container runtime can provide the sandbox prerequisites | Retains Chrome’s sandbox layers. The official image documents SYS_ADMIN and an init process for its setup. |
Launch Chrome with --no-sandbox |
Exceptional case only, when the content opened in Chrome is absolutely trusted and sandbox configuration cannot be used | Removes Chrome’s sandbox protection. Puppeteer strongly discourages running this way. |
If you are forced to use the fallback, Puppeteer shows the option in launch configuration:
const browser = await puppeteer.launch({
args: ['--no-sandbox'],
});This is not the standard Docker fix. A container is not equivalent to Chrome’s own sandbox: disabling the browser sandbox removes an isolation layer, and containerization alone does not restore it. Do not use this setting for arbitrary pages or untrusted input.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot by symptom
- The exact error is “No usable sandbox!” Confirm the host and runtime sandbox prerequisites first. If you use the official image, compare the command with Puppeteer’s documented invocation, including the required capability and
--init. On a custom image, verify user and host-policy configuration before considering a security-reducing workaround. - Chrome exits with a missing-library or shared-object error. Check the actual Chrome binary with
ldd chrome | grep not, then install dependencies appropriate to the selected distribution and Chrome build. Do not substitute a package list for another distribution without verification. - Chrome reports
chrome_crashpad_handler: --database is required. Check whether the browser’s configuration, cache, profile, or crash-reporting paths are writable by the container user. Set the documented XDG paths oruserDataDirto writable locations, or mount a correctly owned writable volume. - The error appears on Ubuntu 23.10 or later with Puppeteer-downloaded Chrome for Testing. Check whether the host’s AppArmor profile for Chrome stable blocks user namespaces. Confirm the host and browser details match Puppeteer’s documented case before changing policy.
- The container starts but child processes are not cleaned up as expected. Add Docker’s
--initor a suitable custom init entrypoint, and review the lifecycle of Chrome processes started by the application.
Or skip the browser setup
If your goal is to capture website screenshots rather than operate Chrome inside your own Docker environment, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF; for example, this cURL request saves a WebP screenshot:
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 the API details. ScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does “No usable sandbox!” mean Puppeteer is not installed?
No. The error reports that Chrome could not use a sandbox in its execution environment; it does not by itself establish whether Puppeteer or Chrome is installed.
Is `–no-sandbox` safe because Chrome is running in Docker?
No. Docker does not make disabling Chrome’s sandbox equivalent to retaining it. Puppeteer restricts that fallback to cases where the opened content is absolutely trusted and strongly discourages it.
Should I use Puppeteer’s `latest` Docker image tag in production?
The documented example uses `latest`, but that tag is mutable. Pin a matching versioned tag when reproducibility matters and check Puppeteer’s current Docker guide for the available image instructions.
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.
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 problems
