First identify whether BackstopJS timed out while navigating to the URL or while waiting for the page’s configured readiness signal. For pages that load successfully but render content later, use a meaningful readySelector or an app-emitted readyEvent; increase readyTimeout only when that condition is correct but legitimately takes longer. A navigation timeout needs a different investigation.
Identify which phase timed out
BackstopJS captures a browser page, so a timeout can occur before or after navigation. Read the exact error and identify the failed phase before changing configuration: readiness settings do not fix a browser that cannot navigate to the URL, and a navigation setting does not make a late-rendered application state ready.
- Navigation timeout: the browser did not finish the configured navigation operation within its limit. Investigate reachability, redirects, authentication, browser/network failures, and the engine’s navigation options.
- Readiness timeout: navigation occurred, but BackstopJS did not observe the configured
readySelectororreadyEventin time.
BackstopJS documents the readiness options and engine configuration in its project documentation. The exact navigation behavior can depend on the engine and versions installed in your project.
Troubleshoot one failing scenario at a time
- Isolate the failure. Run the failing scenario by label, for example
backstop test --filter=<scenarioLabelRegex>. Replace the expression with a pattern matching your scenario label. This reduces noise without changing the scenario itself. - Verify the page state you actually need. In the rendered DOM, check that the proposed readiness selector exists only when the content required for the screenshot is present. A selector that appears too early, never appears, or is not unique to the intended state will not provide a reliable signal.
- Choose a readiness signal. Use
readySelectorwhen a DOM element reliably marks the target state. UsereadyEventwhen the application can explicitly announce that its required data and UI dependencies are ready. - Use a fixed delay only for a known settling period. A delay can accommodate a predictable animation or short post-render pause. It is not a good replacement for a real readiness condition when load time varies.
- Increase the right timeout only when justified. If a correct readiness condition eventually occurs but needs a longer bound, raise
readyTimeout. If the selector is wrong or the event never fires, a larger value only delays the same failure. - If navigation failed, test the runtime path. From the machine or container running BackstopJS, verify the URL is reachable and that authentication, redirects, and browser console or network errors are not preventing navigation. Then review the selected engine’s navigation options.
- If failures span a suite, check resource pressure and environment differences. BackstopJS captures and compares images concurrently. Reduce
asyncCaptureLimitif simultaneous captures appear to overwhelm the environment; this lowers concurrency but does not change page readiness. Compare local and CI/Docker behavior, including browser launch configuration and network access.
Configure readiness for progressive pages
Wait for a rendered element
Set a selector that appears when the content needed for the screenshot is present:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →{
"readySelector": "#results-loaded",
"readyTimeout": 60000
}The selector and 60000ms value are examples, not universal settings. The BackstopJS package documentation lists readyTimeout’s default as 30000ms; choose a value appropriate to the specific application and installed version. See the BackstopJS npm package documentation.
Have the application signal readiness
For a state the application can identify more reliably than a selector, configure an event and emit it only after the dependencies relevant to the screenshot are ready:
{
"readyEvent": "backstopjs_ready",
"delay": 500
}The event name must match what the application emits. The optional delay is in milliseconds and runs after the ready event; keep it only if a known short settling period remains after readiness.
Handle navigation timeouts separately
BackstopJS’s README gives this engine-options example for navigation:
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{
"engineOptions": {
"gotoParameters": { "waitUntil": "networkidle0" }
}
}This is an example, not a default recommendation for every slow page. A page with polling, streaming, or other long-lived requests may never become network-idle. Select a navigation condition that fits the application and the browser engine version in use; then use a page-specific readiness signal if the screenshot depends on content rendered after navigation.
Docker, CI, and suite-wide failures
Check container reachability
A URL that works on the host may not be reachable from the browser inside Docker. BackstopJS’s documentation notes that scenario localhost is not reachable in the Docker setups it describes and gives host.docker.internal as an alternative for Mac and Windows. Confirm the guidance applies to your platform and network setup before changing scenario URLs.
Rank #4
Reduce concurrency only when resource pressure is plausible
asyncCaptureLimit controls how many captures run concurrently. Lowering it can help when simultaneous browser work strains the environment; it is not a readiness signal and does not extend a timeout. If only one scenario fails, focus first on its URL, state, and readiness condition rather than changing suite-wide concurrency.
Common symptoms and fixes
| Symptom | Likely issue | What to check |
|---|---|---|
Timeout names readySelector or readyEvent |
The configured condition did not occur before the readiness bound. | Verify the selector in the rendered DOM or ensure the app emits the configured event after required work completes; then adjust readyTimeout only if that valid condition needs more time. |
| Page navigates, but screenshot misses late content | Capture proceeds before the target application state is ready. | Use a selector or event tied to that state. Add a delay only for a known post-readiness settling interval. |
| Navigation itself times out | The browser cannot complete navigation under the current runtime or navigation behavior. | Check container/CI reachability, redirects, authentication, browser errors, and engine navigation options; do not treat readyTimeout as the fix. |
| Only Docker or CI fails | Network access, host naming, or browser launch behavior differs from local execution. | Test from inside the same runtime and verify its browser configuration and access to the target URL. |
| Many captures fail under load | Concurrent browser work may be overwhelming the environment. | Consider reducing asyncCaptureLimit; this affects concurrency, not the page’s readiness condition. |
Version and diagnosis notes
BackstopJS options and browser-engine behavior can change between releases. Check the locked BackstopJS, Puppeteer, or Playwright versions in the project and base the fix on the exact error. The documented 30000ms default for readyTimeout is from the BackstopJS package documentation; it is a software setting, not a guarantee that any particular page should load within that time.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Or skip the browser setup
If your goal is to capture a page rather than run a BackstopJS visual-regression test, ScreenshotNeo provides a screenshot API and MCP server. A single request can return an image or PDF. For example, this cURL request saves a WebP screenshot; replace the URL with the page you want to capture:
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 options. It removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server offers screenshot tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month—no card required.
Frequently Asked Questions
Does increasing readyTimeout fix every BackstopJS timeout?
No. It applies to readiness checks; a navigation timeout requires investigation of navigation and runtime behavior.
When should I use readySelector instead of readyEvent?
Use a selector when a reliable DOM element marks the required page state; use an event when the application can explicitly signal that its relevant work is complete.
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.
