agent's cypress run timed out waiting for the dev server: how to fix

TL;DR

The Cypress run is not the problem; the dev server was not ready when Cypress started. Add a real readiness gate: start the server, poll its health endpoint until it answers, then launch Cypress. Fixed sleeps and longer Cypress timeouts just move the flake around.

Error

$ npm run dev & npx cypress run
Cypress could not verify that your server is running.
We waited 60000ms for your server to respond at:
YOUR_HOST

Cypress gave up after 60 seconds because nothing was listening yet (or the server crashed on boot).

Steps

1. Reproduce the server start by hand: run your dev command and time how long until the health endpoint answers (a curl retry loop, or npx wait-on YOUR_HOST/health). Expected: you know the real startup time, not a guess.
2. If startup exceeds your CI budget, find out why: check for slow builds, missing env vars, or a port already in use (lsof -i :3000 or ss -ltn). Expected: a named cause, or confirmation it is just slow.
3. Put the readiness gate in CI: start the server in the background, then block on npx wait-on YOUR_HOST --timeout 120000 before cypress run. Expected: Cypress only starts after the server answers.
4. Give the agent a rule: it may not raise Cypress timeouts to "fix" a server-start problem. Expected: timeout changes get rejected in review unless the server gate is already in place.
5. Add a boot smoke check to the pipeline: if the server exits during startup, fail fast with its logs instead of letting Cypress time out. Expected: a clear "server failed to boot" error instead of a mysterious Cypress timeout.

When to use

• Cypress fails with "could not verify that your server is running" or cy.visit() hangs at suite start.
• An agent "fixed" it by bumping timeouts and it still flakes.
• CI starts the dev server and Cypress in the same job.

When not to use

• cy.visit() times out mid-suite on a page that used to load (that is an app or route problem, not server startup).
• The server is up but Cypress cannot reach it (network or proxy config; check baseUrl and CI networking).
• You run Cypress against a deployed preview URL (no local server to gate on).

Tool compatibility

• Cypress 10 through 14; the wait-on npm package or any curl retry loop.
• Any CI (GitHub Actions, GitLab, Jenkins); dev servers on Node, Python, or anything with a health endpoint.

Variant phrasings

Timed out waiting for the dev server at suite start

Same fix whatever the host label is. The gate polls the exact URL in baseUrl.

Agent added a 30-second cy.wait() before cy.visit()

Fixed sleeps are the smell. Replace with the readiness gate; the suite gets faster and deterministic.

Server starts fine locally but not in CI

Usually env vars or build steps missing in CI. Compare the dev command env locally versus the CI job, and log the server output to a file in CI.

Why it happens

Starting a server and running tests are two async processes with no ordering guarantee. CI scripts often background the server and immediately launch Cypress, so on a slow runner Cypress polls a port nobody is listening on yet. Agents then "fix" the symptom with bigger timeouts instead of adding the missing ordering.

Edge cases

• The server binds the port but the app is not ready (DB migrations still running): poll a real health endpoint that checks dependencies, not just TCP on the port.
• Port conflicts from a previous hung run: kill stale processes in CI before starting fresh.
• wait-on succeeding but the first cy.visit() still slow: that is app warmup (JIT, cold caches); a single warmup visit before the suite is fine, a sleep is not.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_69Wrv3OwAjBUftCMgilixw