cy.visit() Failed: Your Dev Server Is Not Running

It is 9:40 AM, your pull request is green everywhere except the one Cypress job that matters, and the error is brutally unhelpful: cy.visit() failed trying to load some URL, connection refused. You did not change the test. You did not change the app. Rerun the job and it passes — or fails on a different spec this time. Congratulations, you have met the most common Cypress failure in existence, and it has almost nothing to do with Cypress.

In nearly every case, cy.visit() fails for one of three boring reasons: nothing is listening at that address, Cypress is aimed at the wrong address, or the server exists but is not ready yet. The browser asked the OS to open a connection, the OS said no, and Cypress reported exactly that. There is no retry that can fix a server that is not there, which is why re-running the spec feels like rolling dice.

This article turns that dice roll into a checklist. You will learn how baseUrl and CYPRESS_BASE_URL decide where visits go, how to prove in ten seconds whether the server is up, and how to wire the readiness gate — start-server-and-test or wait-on — so Cypress physically cannot start before your app answers. Follow it once and this entire failure category disappears from your CI forever.

Why cy.visit() Fails When the Dev Server Is Not Running

When cy.visit() fails, the browser is telling you something precise: it tried to open a connection to a host and port, and the operating system refused it. That refusal has exactly one meaning — no process is accepting connections there right now. It does not mean your test is wrong, your selectors are stale, or Cypress is broken. It means the restaurant is closed and the critic is standing outside an empty building.

The confusion comes from how close everything looks to working. Your code compiles. Your unit tests pass. Cypress launches, the browser opens, and then the very first visit dies. Because the failure appears inside a test runner, your instincts blame the test. Fight that instinct. Open a second terminal while Cypress is failing and run curl -v against the exact URL. If curl also fails, you have proven in five seconds that no test edit can help — the server is simply not there.

This happens most often for embarrassingly simple reasons. You forgot to run npm run dev. You started it in a terminal you later closed. You are on a fresh machine where dependencies were never installed so the server crashed on boot. Or CI started Cypress and the server at the same moment and Cypress won the race. Every one of these is an environment problem wearing a test-failure costume, and the fix is to confirm the server before you ever read the spec.

// cypress.config.js — one baseUrl, overridable per environment
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    // Every cy.visit('/') resolves against this origin
    baseUrl: 'http://localhost:3000',
    // Fail fast instead of hanging on a dead server
    defaultCommandTimeout: 8000,
    setupNodeEvents(on, config) {
      // Log the resolved URL so CI output shows where visits go
      console.log(`Cypress baseUrl: ${config.baseUrl}`)
      return config
    },
  },
})

// Terminal: override without editing the file
// CYPRESS_BASE_URL=https://staging.example.com npx cypress run

baseUrl vs Absolute URLs: How Cypress Resolves cy.visit()

The baseUrl setting in cypress.config.js is the prefix Cypress prepends to every relative visit. With baseUrl: 'http://localhost:3000', calling cy.visit('/login') navigates to http://localhost:3000/login. Call cy.visit('http://other-host:4000/x') with a full URL and baseUrl is ignored entirely for that visit. Most wrong-address failures are developers mixing these two modes without realizing which rule applies.

Ports drift silently as projects evolve. Create React App defaulted to 3000, Vite defaults to 5173, Angular to 4200 — and any of them can move when the port is busy or a config changes. If your specs hard-code cy.visit('http://localhost:3000/...') in twenty places while the app now boots on 5173, you get a suite where some specs pass (the relative ones) and others fail (the absolute ones), which looks like flakiness but is really just stale addresses.

The durable fix is a single source of truth: one baseUrl in config, relative visits everywhere, and absolute URLs only where a test genuinely targets a second service. When a visit fails, diff the config value against the address your server prints on boot — host and port, character by character. Nine times out of ten the mismatch is staring at you from those two lines.

// Cypress resolves relative visits against baseUrl
// baseUrl: 'http://localhost:3000'

cy.visit('/')           // -> http://localhost:3000/
cy.visit('/login')      // -> http://localhost:3000/login
cy.visit('dashboard')   // -> http://localhost:3000/dashboard

// Absolute URLs IGNORE baseUrl completely
cy.visit('http://localhost:4000/admin') // goes to :4000, always

// Debug helper: print where you are actually going
cy.visit('/login')
cy.url().should('eq', 'http://localhost:3000/login')

CYPRESS_BASE_URL and Per-Environment Overrides

The CYPRESS_BASE_URL environment variable overrides the baseUrl from your config file for a single run, with no edits and no commits. Run CYPRESS_BASE_URL=https://staging.example.com npx cypress run and every relative visit now targets staging. This is the mechanism that lets one suite run against local, preview, staging, and production simply by changing the environment around it.

It only works if your specs cooperate. Any absolute URL in a spec bypasses baseUrl and therefore ignores the override — a suite full of cy.visit('http://localhost:3000/...') calls will keep hitting localhost no matter what the variable says. That is the classic reason staging runs mysteriously test a developer's laptop address. Audit for absolute visits before you trust environment overrides.

The second trap is assuming the variable exists where it matters. It is set on your laptop but missing in CI, or set in CI but missing in a teammate's shell, and suddenly identical commits behave differently per machine. Treat CYPRESS_BASE_URL like any other deployment input: declare it in each CI environment explicitly, echo its value at the start of the job, and assert in a support file that Cypress.config('baseUrl') is defined. A missing URL should fail the job in one line at second zero, not as forty cryptic visit errors.

Wait for Readiness: start-server-and-test and wait-on

Starting a server and waiting for it are two different events, and the gap between them is where flaky cy.visit() failures live. Frameworks like Vite and Next.js compile bundles, load routes, and bind the port in stages — a process can exist for 30 seconds before its first HTTP response. Launch Cypress alongside the server with a bare & or concurrently and you are racing the compiler on every run.

The fix is a readiness gate: a tool that polls the URL and only launches Cypress after it answers. start-server-and-test is the standard choice — it starts your dev command, waits for the resource, runs Cypress, then cleans up the server. wait-on is the lighter alternative when something else owns the server lifecycle and you only need the waiting step. Either one converts a timing race into a guaranteed ordering.

Note what the gate waits on: the HTTP resource, not the process. Polling http://localhost:3000 proves the port accepts connections and the app responds. Watching for a PID or a log line proves far less — a process can print cheerful startup banners minutes before it serves traffic. If your CI still flakes after adding the gate, check that you are polling the same host and port Cypress visits; gating on 127.0.0.1 while visiting localhost (or vice versa) re-opens the race through a DNS-shaped hole.

// package.json — Cypress cannot start before the app answers
{
  "scripts": {
    "dev": "vite --port 3000",
    "cy:run": "cypress run",
    "test:e2e": "start-server-and-test dev http://localhost:3000 cy:run"
  },
  "devDependencies": {
    "start-server-and-test": "^2.0.0"
  }
}

// What start-server-and-test does, step by step:
// 1. runs `npm run dev`
// 2. polls http://localhost:3000 until it responds
// 3. runs `npm run cy:run`
// 4. shuts the dev server down afterwards

// One-off equivalent without the package:
// npx wait-on http://localhost:3000 && npx cypress run

CI Failures: Ports, Hosts, and Health Checks

CI amplifies every local sloppiness because the machine is cold, slow, and shared. Dependencies install from scratch, the framework compiles with an empty cache, and Cypress starts the instant the previous step exits. A suite that passes on your warm laptop can fail every CI run simply because boot takes 40 seconds there and 4 seconds at your desk. The failure looks identical to a broken app, which sends the team chasing ghosts.

Harden the CI job in three layers. First, bind the host explicitly — --host 0.0.0.0 — so the server is reachable however the runner routes traffic, and log the bound address so the job output proves where it listens. Second, gate with wait-on plus a generous timeout (cold boots are slow) so Cypress cannot start early. Third, add a curl --fail step between the gate and Cypress: if the app itself is crashing on boot, you get a one-line network error naming the URL instead of forty failing specs.

Keep ports pinned per project and document them where the team will actually see them — the README and the workflow file, not tribal memory. When Docker enters the picture, verify the container port mapping (-p 3000:3000) and remember that localhost inside a container is not the host's localhost. Most Docker visit failures are fixed by binding 0.0.0.0 in the container and visiting the mapped host port from Cypress.

# .github/workflows/e2e.yml — health-check before Cypress
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      CYPRESS_BASE_URL: http://localhost:3000
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Start app in background
        run: npm run dev -- --host 0.0.0.0 --port 3000 &
      - name: Wait for readiness
        run: npx wait-on http://localhost:3000 --timeout 120000
      - name: Prove the app answers (fails fast with a clear log)
        run: curl --fail http://localhost:3000/ -o /dev/null
      - name: Run Cypress
        run: npx cypress run

A Startup Checklist That Ends cy.visit Flakes

End this failure category with a checklist you run once and then encode into scripts so nobody relies on memory. Confirm the dev server boots cleanly with npm run dev and loads in a real browser at the documented URL. Confirm baseUrl in cypress.config.js matches that URL exactly, and that every spec uses relative visits. Confirm CYPRESS_BASE_URL is set in each CI environment and echoed at job start. Confirm the launch path goes through start-server-and-test or wait-on, never a bare background &. Confirm a curl health check sits between readiness and Cypress.

Then make the setup self-defending. Assert baseUrl in cypress/support/e2e.js so a missing config throws a named error before the first test. Log the resolved baseUrl via setupNodeEvents so every CI run records what the suite aimed at. Pin the port per project and reject drive-by changes to it in code review — a port change without updating config and docs is a guaranteed red pipeline.

Do this and cy.visit() failures stop being mysteries. When a visit fails in the future, the checklist tells you in seconds whether the server died (health check red), the address moved (logs disagree), or the app genuinely broke (server up, page down) — three different owners, three different fixes, zero guessing.