Cypress "cy.visit() failed ... ECONNREFUSED" in CI

By Kaveh Alemi·Latchkey

cy.visit() tried to open the URL but the connection was refused, meaning nothing was listening there yet. In CI this is the app server not being ready before the test started, or a baseUrl pointing at the wrong port.

What this error means

A test fails with "cy.visit() failed trying to load: http://localhost:3000/ ... We received this error at the network level: Error: connect ECONNREFUSED 127.0.0.1:3000".

cy.visit() failed trying to load:

http://localhost:3000/

We received this error at the network level:
  > Error: connect ECONNREFUSED 127.0.0.1:3000

Common causes

The app server had not started yet

Cypress began before the dev/prod server bound its port, so the very first visit is refused.

baseUrl points at the wrong port or host

The configured baseUrl does not match where the app actually listens, so every visit is refused.

How to fix it

Wait for the server before running Cypress

Use wait-on (or the cypress-io GitHub Action's wait-on) so tests start only after the URL responds.

- run: npm run start &
- run: npx wait-on http://localhost:3000
- run: npx cypress run

Set baseUrl to the real address

Point baseUrl at the exact host and port the app binds so visits resolve.

module.exports = defineConfig({
  e2e: { baseUrl: 'http://localhost:3000' },
});

How to prevent it

• Gate Cypress on a wait-on / health check for the server URL.
• Keep baseUrl aligned with the server's bind address.
• Start the server in the same job and confirm it is up before testing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation