How to Fix BackstopJS Chrome Launch Errors

BackstopJS Chrome launch errors have several different causes. Start with the full error and Chrome stderr, then check whether the message points to Docker running as root, a Linux sandbox or AppArmor policy, Windows file permissions, or a browser that launched but could not reach a page. Use engineOptions for launch arguments. Do not add --no-sandbox as a generic fix: it reduces Chrome’s security and Puppeteer strongly discourages running without the sandbox.

1. Identify the failure before changing configuration

Capture the complete first error line and Chrome stderr. Record the operating system, whether the process runs in Docker or CI, and the BackstopJS and Puppeteer versions. Then inspect the root-level engine and engineOptions in backstop.json. BackstopJS uses Puppeteer by default and also supports Playwright; launch settings depend on the engine selected. See the BackstopJS README and Puppeteer troubleshooting guide.

Error clue	Likely area	First check
Running as root without --no-sandbox is not supported	Docker or another root-run environment	Container user and Chrome sandbox configuration
No usable sandbox!	Linux sandbox setup	Host sandbox support and, on Ubuntu 23.10+, AppArmor policy
Access is denied near Chrome files	Windows filesystem permissions	Chrome executable permissions and Puppeteer version
Chrome starts, then navigation times out	URL reachability, memory, or page loading	Scenario URL from inside the container and available memory

2. Fix Docker root and sandbox errors

If the message specifically says Chrome is running as root without --no-sandbox, first see whether Chrome can run as a non-root user with a working sandbox. BackstopJS documents this argument as a workaround in its Docker troubleshooting guidance, particularly for configurations generated before version 3.5. Puppeteer strongly discourages disabling the sandbox, so use this only in a trusted, controlled environment after considering the security tradeoff.

{
  "engine": "puppeteer",
  "engineOptions": {
    "args": ["--no-sandbox"]
  }
}

Merge the argument into the existing engineOptions; do not replace other required settings accidentally. If you already have arguments, keep them in the same array. This snippet addresses the explicit root/sandbox message only. It does not fix a missing Chrome executable, bad permissions, an unreachable target, or a timeout.

3. Diagnose Linux sandbox and AppArmor failures

For No usable sandbox!, check the host’s sandbox configuration rather than assuming every Linux failure needs --no-sandbox. Puppeteer notes that Chrome can crash if it cannot find a usable sandbox. On Ubuntu 23.10 and newer, an AppArmor policy may prevent Chrome for Testing from using user namespaces. Match the error, distribution, and browser setup to the Puppeteer guidance before changing host policy. Disabling the sandbox lowers isolation and is not Puppeteer’s recommended solution.

4. Diagnose Windows permission errors

If Chrome launch output reports Access is denied around downloaded Chrome files, verify the executable path and its filesystem permissions, along with the Puppeteer version. Puppeteer v22.14.0 attempts to configure Chrome permissions through setup.exe. The troubleshooting guide describes a manual icacls adjustment for older versions or cases where the problem persists. Apply that procedure only after confirming the affected path and permissions; do not copy a path-specific command blindly.

5. Separate browser launch from page navigation

If Chrome starts successfully but cannot open the scenario page, this is usually a reachability or navigation problem rather than a launch failure. In Docker, localhost refers to the container itself. When a BackstopJS container needs to reach an application running on the host, the BackstopJS README gives host.docker.internal as an example for macOS and Windows. Check the URL from the container’s network context.

BackstopJS also notes that headless Chrome needs sufficient memory. If the browser starts and then hangs, times out, or behaves inconsistently, inspect Docker memory limits and the navigation timeout separately. A larger timeout cannot repair a browser process that never launched, and changing sandbox flags cannot repair a host URL that the container cannot reach.

6. Use BackstopJS debugging options

Enable debug in the BackstopJS configuration to get verbose logging while narrowing down the failure. debugWindow can expose browser state for inspection, but a visible browser window is often unsuitable in headless CI. Use these options to establish whether Chrome starts, whether navigation begins, and where the scenario stops.

{
  "debug": true
}

Add this to the existing configuration rather than discarding project-specific settings. Turn verbose logging back off when diagnosis is complete if the additional output is not useful.

7. A practical troubleshooting sequence

1. Save the full error text and Chrome stderr; note OS, container/CI context, BackstopJS version, and Puppeteer version.
2. Check the configured engine and root-level engineOptions.
3. For a root/sandbox message, inspect the Docker user and sandbox setup. Consider the documented --no-sandbox workaround only with its security cost understood.
4. For Linux No usable sandbox!, inspect sandbox support and possible AppArmor restrictions.
5. For Windows access errors, verify the Chrome file path and permissions, then check the Puppeteer version before applying the documented permission procedure.
6. If Chrome launches, verify the scenario URL from the container and check memory and navigation timeout.
7. Compare old issue reports with your actual versions. BackstopJS issue #803 describes a SingletonLock report from v3.2.17 in 2018; it is not evidence that the same fix applies to current versions.

8. Performance, reliability, and cost considerations

Keep diagnosis focused on the earliest failing stage. Repeated retries of a launch failure consume CI time without addressing its cause. For post-launch delays, sufficient container memory and a reachable target URL matter; distinguish those from process startup. Treat disabling the sandbox as a security tradeoff, not a performance optimization. The cited BackstopJS and Puppeteer guidance provides no universal memory figure or timeout value, so size these for your workload and environment instead of relying on an invented number.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Instead of maintaining a local Chrome/BackstopJS launch environment for a screenshot, make one request:

See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, no card required.

FAQ

Does BackstopJS use Puppeteer?

Puppeteer is the default engine described by the BackstopJS README. Playwright is also available, so verify your configured engine before applying engine-specific advice.

Should I always add --no-sandbox in Docker?

No. It is a documented workaround for a specific root/sandbox condition, and Puppeteer strongly discourages running Chrome without its sandbox.

Is SingletonLock a general fix target?

No. The cited BackstopJS report concerns a specific 2018 v3.2.17 setup. Use the current error and versions to guide diagnosis.