Free tools Windows power users keep installed
One-click scans. No signup required.
To fix Puppeteer timeout errors in Docker, first identify what timed out: launching Chrome, navigating to a page, or waiting for a page condition. A longer timeout helps only when the browser is otherwise starting and working correctly. Missing Linux libraries, incompatible browser versions, unwritable profile paths, sandbox configuration, or runtime CPU limits require different fixes.
Identify which Puppeteer operation timed out
Start with the complete error message and stack trace. A timeout value by itself does not reveal whether Chrome failed to start or a page operation took too long. In particular, Navigation timeout of 30000 ms exceeded points to navigation, while a launch error or launch timeout points to starting the browser process.
- Launch: Puppeteer is starting Chrome. Check the executable, version compatibility, shared libraries, permissions, writable paths, and container runtime settings.
- Navigation: Chrome has started, but the page did not satisfy the navigation wait condition before its limit. Investigate the site, network access, and chosen wait condition.
- Selector or other page wait: The browser is running, but a requested element or condition did not become true. Check the selector, page state, and application behavior.
Do not change a page navigation timeout to solve a launch failure, or vice versa. A large timeout can hide the symptom while leaving the underlying problem intact.
Fix browser launch failures in Docker
Check the browser and Puppeteer versions
Confirm that the browser executable exists in the image and that the installed Puppeteer version is compatible with it. A deployment can differ from a local machine because its image may contain a different browser, an outdated binary, or no browser at all. Pin compatible versions in your deployment and check the current Puppeteer Docker guide rather than relying on an old image tag.
#1 Best Overall
The current Docker guide identifies its documented page as version 25.12.0. It describes an official image with Chrome for Testing, required dependencies, and a pre-installed Puppeteer version. The image is published through GitHub Container Registry and offers latest and version-specific tags. Because tags and compatible versions can change, use a version-specific tag where reproducibility matters and verify its compatibility with your installed Puppeteer.
Use the official image or install your custom image’s dependencies
If you build on a custom base image, Chrome may be present but unable to start because a required shared library is missing. Check the browser-process output and install the dependencies appropriate to your distribution. The Puppeteer troubleshooting guide includes dependency guidance, but package names and requirements vary by distribution and can change. Follow the current instructions for the base image you actually deploy; do not copy a dependency list for a different Linux distribution.
When building a custom image, the official Puppeteer Dockerfile is a useful starting point, as the Docker guide recommends. Re-check it and the current dependency list when changing your base image or browser version.
Collect Chrome’s startup output
Enable Puppeteer’s dumpio launch option to forward browser stdout and stderr to the Node.js process streams. Then inspect the container logs for missing libraries, permission failures, or Chrome startup errors.
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 →const browser = await puppeteer.launch({ dumpio: true });This is diagnostic output, not a fix by itself. Capture the full error and logs from the same image and runtime that fail; a local run may not reveal a container-specific dependency or permission problem. See the launch options reference for the current option documentation.
Treat Alpine as a version-specific case
The troubleshooting guide says Chrome does not support Alpine out of the box and requires compatible dependencies and matching browser versions. It also notes reports that Chromium in Alpine 3.20 was causing Puppeteer timeouts, while downgrading to Alpine 3.19 fixed those cited cases. That is guidance tied to the versions and reports described on the living troubleshooting page, not a guarantee that the same downgrade will fix every current deployment. Verify present compatibility before changing distribution or versions.
Make Chrome’s runtime environment usable
Provide writable configuration, cache, and profile paths
Chrome writes configuration, cache, and profile data at startup. A read-only container filesystem, restrictive mount, or incorrect file ownership can stop Chrome before Puppeteer connects. The troubleshooting guide recommends pointing XDG configuration and cache paths to writable locations such as /tmp, setting Puppeteer’s userDataDir to a writable location, or mounting writable volumes and ensuring the browser user owns them.
process.env.XDG_CONFIG_HOME = '/tmp/.config';
process.env.XDG_CACHE_HOME = '/tmp/.cache';
const browser = await puppeteer.launch({
userDataDir: '/tmp/puppeteer-profile',
});Use paths that exist or can be created by the container’s browser user. If you mount a volume, check ownership and write permissions inside the running container, not only on the host. The error chrome_crashpad_handler: --database is required can occur when Chrome lacks writable paths.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRank #3
Configure sandboxing and process cleanup
The current official Puppeteer Docker guide says its image runs Chrome in sandbox mode and requires the Docker SYS_ADMIN capability. Its example also uses --init; the guide recommends an init process or suitable custom entrypoint so Chrome’s child processes are managed properly.
docker run --init --cap-add=SYS_ADMIN your-puppeteer-imageApply the capability and process-management instructions for the official image and your deployment environment. Do not treat --no-sandbox as a universal timeout fix: it changes the browser’s security posture, and the official image documentation describes sandboxed operation.
Check runtime CPU behavior on Cloud Run
Puppeteer’s troubleshooting page identifies a Cloud Run-specific cause of apparently slow background launches: CPU may be disabled after an HTTP response is sent. If browser work continues after responding, launch the browser before sending the response or configure CPU to remain allocated for background work, following the current Cloud Run settings for your service. This is a platform-specific runtime issue, not a general Docker timeout setting.
Fix navigation and page-wait timeouts separately
If Chrome launches successfully but a navigation times out, diagnose the page operation instead of reinstalling browser dependencies without evidence. Check whether the target is reachable from inside the container, whether the page is still loading, and whether the wait condition matches what the task needs. For example, waiting for network idle can be unsuitable for a page that keeps connections open; waiting for a selector is more appropriate when the task depends on a specific element.
Likewise, if a selector wait expires, verify that the selector is correct and that the relevant content is expected to appear in the page state Puppeteer observes. A launch timeout setting does not control these page-level waits. Avoid increasing multiple unrelated timeouts at once: changing one limit at a time makes it easier to tell whether the diagnosed failure has changed.
Increase the launch timeout only after checking startup
Puppeteer’s launch option timeout controls how long it waits for the browser to start. The documented default is 30 seconds; setting it to 0 disables that wait limit. The current behavior is documented in the launch options reference.
const browser = await puppeteer.launch({
timeout: 60_000,
});Use a longer finite limit only when the browser is valid and starts successfully, but startup legitimately exceeds the existing limit in your environment. Disabling the limit can leave a process waiting indefinitely if Chrome is stuck. Neither setting installs missing libraries, corrects a browser mismatch, makes a read-only path writable, supplies a required capability, or restores CPU allocation.
Choose the fix by failure class
| Evidence | Likely area | Next action |
|---|---|---|
| Chrome exits before Puppeteer connects; logs mention a shared library | Custom image dependencies | Install the missing dependency for the chosen distribution and verify the current Puppeteer guidance. |
| Executable missing or browser and library versions do not match | Image contents or version compatibility | Use a compatible browser/Puppeteer pair; verify the image tag and pin versions. |
| Crashpad or profile errors; container uses restricted or read-only paths | Writable configuration, cache, or profile locations | Use writable paths or an appropriately owned writable mount. |
| Official image sandbox setup fails | Container capability or process lifecycle | Follow the current official image instructions for SYS_ADMIN and an init process. |
| Work appears stalled only after an HTTP response on Cloud Run | CPU allocation after response | Launch before responding or configure CPU allocation for background work. |
| Browser is running but navigation or selector wait expires | Page-level condition, reachability, or site behavior | Inspect the page operation and wait condition; tune that operation’s limit only if justified. |
| Valid browser startup is simply slower than the launch limit | Launch timeout setting | Raise the launch timeout to a suitable finite value after ruling out startup faults. |
Or skip the browser setup
If your goal is to produce screenshots rather than maintain a Puppeteer container, ScreenshotNeo provides a website screenshot API and MCP server. Its clean-shot options accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each 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. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
One GET request returns an image or PDF. For example, this cURL request saves a WebP screenshot; see the ScreenshotNeo API documentation for available options and formats.
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
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo also has a free plan with 1,000 shots per month and no card required; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Frequently Asked Questions
Does Puppeteer’s 30-second launch timeout also control page navigation?
No. The launch timeout applies to starting the browser; navigation and page waits are separate operations.
Should I use –no-sandbox to fix a Docker timeout?
Not as a blanket fix. The official Puppeteer image instructions describe sandboxed Chrome and require SYS_ADMIN; changing sandbox behavior has security implications.
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.
