BackstopJS "Puppeteer Navigation timeout" in CI

By Daniel Zoghalchali·Latchkey

BackstopJS drives Puppeteer to load each scenario URL. If the page does not finish loading before the timeout, Puppeteer throws "Navigation timeout ... exceeded" and the scenario errors instead of comparing.

What this error means

A scenario fails with "Error: Navigation timeout of 30000 ms exceeded." Often the app under test was not started, or the URL points to localhost which is not reachable from inside the Backstop container.

Puppeteer encountered an error while running scenario "Home"
Error: Navigation timeout of 30000 ms exceeded

Common causes

The app under test was not running

The scenario URL has nothing serving it, so navigation never completes and times out.

localhost is not reachable from the container

Inside the Backstop Docker container, localhost refers to the container, not the host running the app. The URL must target the host or a linked service.

How to fix it

Start the app and wait before testing

1. Start the app and wait until it responds before running Backstop.
2. From inside the container, target host.docker.internal (or a service name) instead of localhost.
3. Raise the scenario readySelector or timeout if the app is slow to render.

npx wait-on http://localhost:3000 && npx backstop test

Use a reachable URL from the container

Point scenarios at the host gateway so the container can reach the app.

"scenarios": [
  { "label": "Home", "url": "http://host.docker.internal:3000/" }
]

How to prevent it

• Wait for the app to be reachable before running Backstop.
• Use host.docker.internal or a service name, not localhost, inside containers.
• Set realistic navigation timeouts for slow-rendering pages.

Frequently asked questions

Related guides

References

• GitHub Actions documentation