Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
“Browser has disconnected” means Puppeteer lost its connection to Chrome or Chromium; it does not, by itself, say why. The browser may have crashed or exited, Docker may have terminated it, or your code may have intentionally detached the client. Capture the browser’s output first, then check process cleanup, browser dependencies and versions, sandbox configuration, writable paths, and container limits. Avoid treating a copied launch flag as a diagnosis.
What the error means—and what it does not
Puppeteer controls a browser through a connection. An error such as Navigation failed because browser has disconnected! says that connection was lost while Puppeteer was working. It does not establish that navigation itself caused the failure, nor does it distinguish a browser crash from an intentional disconnect or process termination.
Start by determining whether Chrome exited or whether your application merely stopped controlling a browser that is still running. Logs and the exact deployment details matter: reports of this message span different versions, images, workloads, and failure points, so no one cause or flag can be assumed to apply to every Docker deployment.
Collect the details that make the failure diagnosable
Before changing configuration, record the environment that produced the error. A useful incident note includes:
#1 Best Overall
- Docker image name and tag, including the base distribution.
- Node.js and Puppeteer versions.
- The actual Chrome or Chromium executable path and its version.
- The container command, entrypoint, user, and capability settings.
- CPU, memory, and shared-memory limits, if configured.
- The operation that failed: launch, navigation, PDF generation, or a concurrent workload.
These details help distinguish an incompatible browser/dependency setup from a process-lifecycle or runtime issue. Preserve the relevant container and browser output around the failure, rather than relying on the Puppeteer exception alone.
Capture Chrome’s output before changing launch settings
Enable dumpio in Puppeteer’s launch options so browser output is forwarded to the Node process’s stdout and stderr. For example:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: true,
dumpio: true,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'load' });
console.log(await page.title());
} finally {
await browser.close();
}
})();Run the same container workload and retain the output surrounding the disconnect. The example deliberately uses a basic page and a simple load condition; it is a starting reproduction, not a claim that every site should use that wait condition. If the browser exits, its output may reveal why. If output does not explain the loss, move to the checks below rather than piling on flags.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For deeper protocol diagnosis, Puppeteer documents enabling protocol logging with NODE_DEBUG="puppeteer:*" and inspecting browser.debugInfo.pendingProtocolErrors for outstanding protocol calls. Logs can contain sensitive URLs, headers, or other request details; inspect and redact them before sharing.
Check whether your own code disconnected or closed the browser
Search the application and cleanup paths for browser.disconnect(), browser.close(), process signals, and error handlers. A disconnect is not the same operation as closing Chrome: Puppeteer’s API specifies that disconnect() detaches the client while leaving the browser process running. If a later page operation uses that detached client, the resulting connection error may look like a browser crash even when Chrome has not exited.
Rank #2
Review cleanup logic around timeouts and exceptions, especially if browser instances are shared across jobs. Ensure that one request’s cleanup cannot close or disconnect a browser another operation still expects to control. Conversely, if Chrome’s process actually exited, investigate its output and the container conditions rather than changing the navigation code alone.
Verify the browser binary, libraries, and version pairing
Inside the image, confirm that the executable Puppeteer launches is the one you expect, and verify that its required shared libraries are present. Puppeteer’s troubleshooting guidance describes using ldd to check Linux dependencies. Its Linux guidance also warns that Chrome does not work on Alpine out of the box without compatible system dependencies; a setup that works on Debian or Ubuntu should not be assumed to transfer unchanged to Alpine.
Free tools Windows power users keep installed
One-click scans. No signup required.
Check that the browser build is compatible with the Puppeteer version in use. A custom image can accidentally combine a Puppeteer release with a separately installed browser or system libraries that do not match its assumptions. Use the troubleshooting guidance for the versions actually deployed, not an old version-specific timeout note as a universal rule.
If the browser cannot launch cleanly or reports missing libraries, correct the image and browser pairing first. Repeated navigation retries will not repair a missing shared library or an invalid executable path.
Review Docker’s sandbox and process-management setup
Puppeteer provides a Docker image containing Chrome for Testing and its required dependencies. Its documented example runs with --init --cap-add=SYS_ADMIN: the image uses Chrome’s sandbox and documents the capability requirement. The guide also calls for an init process, either Docker’s --init flag or an equivalent custom entrypoint, so processes started by Puppeteer are managed properly. These are instructions for Puppeteer’s documented image setup; a different base image or runtime may need a deliberately adapted configuration.
For example, the documented runtime shape is:
docker run --init --cap-add=SYS_ADMIN your-puppeteer-imageCompare your actual command and entrypoint with the official Puppeteer Docker guide. An init process helps manage browser child processes; it does not, on its own, fix missing libraries, an incompatible browser, or application code that closes a browser too early.
Recommended Free Tools
Do not make --no-sandbox the routine fix. Puppeteer strongly discourages running without a sandbox because it reduces protection for the host when rendering untrusted web content. The official Docker image’s documented route is sandboxed execution with the required capability. Only consider disabling the sandbox when content is absolutely trusted and the runtime cannot support the sandbox; treat that as a security trade-off, not a generic stability flag.
Make Chrome’s profile and cache paths writable
Restricted, read-only, or non-root containers can prevent Chrome from writing its profile, configuration, or cache. Puppeteer’s troubleshooting guide describes pointing XDG configuration and cache locations at /tmp and using an explicit writable userDataDir when needed. Confirm that the directories exist and that the process user can write to them.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({
headless: true,
userDataDir: '/tmp/puppeteer-profile',
env: {
...process.env,
XDG_CONFIG_HOME: '/tmp/.config',
XDG_CACHE_HOME: '/tmp/.cache',
},
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'load' });
} finally {
await browser.close();
}
})();This example assumes those paths are writable in the container. Adapt the paths to the deployed Puppeteer and Node versions, and consult Puppeteer’s troubleshooting guidance for the current dependency and path recommendations.
Reduce the workload to a small reproduction
Once the environment and logs are recorded, reduce the failing job to one browser and one page on a simple, stable URL. Then add the real target and workload elements one at a time:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors- Confirm the browser launches and completes a basic navigation.
- Try the target URL with the same navigation wait condition.
- Add PDF generation, external resources, or other work used by the failing job.
- Increase concurrency only after the single-operation case is understood.
This sequence helps establish whether a specific operation or workload is involved. External resources, HTTPS certificate problems, a networkidle0 wait, or high concurrency can appear in individual failures, but an anecdotal report does not prove any of them is the general cause. A navigation/network problem and a browser process that has actually exited are different findings; use output and a minimal reproduction to separate them.
Why common flag recipes are not a diagnosis
There is no established universal fix for this error based on --single-process, --disable-dev-shm-usage, or a bundle of Chromium flags. Historical reports include --single-process in failing or multi-flag configurations; they do not establish that it fixes disconnects. A flag can also change security or runtime behavior without addressing the actual cause.
Prefer the maintained Docker guidance, browser output, and one-change-at-a-time tests. Add a launch argument only when a specific error or supported configuration calls for it, and document why it is present so future maintainers can distinguish a needed setting from a copied workaround.
Troubleshooting by symptom
| What you observe | What to check | Next action |
|---|---|---|
| Chrome fails at launch or exits immediately | Browser executable, version pairing, shared libraries, and browser stderr | Verify the binary and dependencies inside the image; use Puppeteer’s Linux troubleshooting guidance. |
| Chrome remains running, but Puppeteer reports a disconnect | browser.disconnect(), cleanup handlers, signals, and shared browser ownership |
Trace which code path detached or closed the client; isolate cleanup between jobs. |
| Failure appears only in a custom or restricted image | Sandbox capability, entrypoint/init behavior, runtime user, and writable profile/cache paths | Compare with the official Docker image setup and make required paths writable. |
| Failure appears only on Alpine | Compatibility of the chosen browser and installed system dependencies | Follow current Alpine-specific guidance; do not assume Debian/Ubuntu dependencies suffice. |
| Only a particular navigation or workload fails | Browser output, wait condition, external resources, PDF work, and concurrency | Reproduce with a simple page, then add the workload back in controlled steps. |
| Protocol calls remain unresolved when the error occurs | Puppeteer protocol logs and pending protocol errors | Enable documented protocol diagnostics and redact sensitive data before sharing. |
Choose between Puppeteer’s image and a custom base image
| Approach | Advantages | Operational costs and conditions |
|---|---|---|
| Puppeteer-maintained Docker image | Includes Chrome for Testing and required dependencies; its documented setup specifies sandbox and process-management expectations. | Use the image’s guidance for its version and provide the documented capability and init behavior. |
| Custom base image | Lets you control the operating-system image and installed components. | You own browser/Puppeteer compatibility, shared-library installation, writable paths, and container runtime configuration. |
For a custom image, record the exact browser and operating-system versions and validate them when either changes. For either route, browser output and the deployed container configuration remain essential: the documented image reduces dependency guesswork, but it cannot identify an application-level disconnect on its own.
Or skip the browser setup
If your goal is to obtain a website screenshot rather than debug a Puppeteer container, ScreenshotNeo is a screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. For example, save a WebP screenshot of a URL with cURL:
Best Value
- Used Book in Good Condition
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 setup and parameters. ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate 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. Those plans and features are listed at ScreenshotNeo. Sign up free for 1,000 screenshots a month—no card required.
Frequently Asked Questions
Does adding `await` fix “Browser has disconnected”?
No. `await` affects how JavaScript waits for an operation; it does not explain why the browser connection was lost. Check browser output and whether the browser process exited or your code detached it.
Should I add `–no-sandbox` in Docker?
Not as a default fix. Puppeteer strongly discourages disabling the sandbox; its documented Docker setup uses sandboxed Chrome with the required capability.
Is `–single-process` a proven fix for this error?
No universal fix is established. Historical reports that include the flag do not demonstrate that it prevents browser disconnects.
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.
