cypress-io/cypress · error · Error

Tests cannot run without a reference to Cypress!

Error message

Tests cannot run without a reference to Cypress!

What it means

Thrown by the @cypress/webpack-dev-server browser-side aut-runner init when `parent.Cypress` is undefined. The runner copies window.Cypress from the opener/parent window; if that source window has no Cypress instance (the server did not inject the Cypress runtime), the AUT cannot wire commands and refuses to run. Cypress.action('app:window:before:load') and onSpecWindow never execute.

Source

Thrown at npm/webpack-dev-server/src/aut-runner.ts:8

/* eslint-env browser */

export function init (importPromises: Array<() => Promise<void>>, parent: Window = (window.opener || window.parent)) {
  // @ts-expect-error
  const Cypress = window.Cypress = parent.Cypress

  if (!Cypress) {
    throw new Error('Tests cannot run without a reference to Cypress!')
  }

  Cypress.onSpecWindow(window, importPromises)
  Cypress.action('app:window:before:load', window)
}

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Do not open the spec/runner HTML directly — always drive CT through `cypress open --component` or `cypress run --component`.
2. If using a custom dev server, ensure Cypress's injection (via Cypress.action('app:window:before:load') / the CT webpack plugin) is not stripped.
3. Confirm the parent runner window is alive when init executes (avoid navigation away during load).
4. Reinstall/upgrade @cypress/webpack-dev-server to match your Cypress version so the injection contract holds.

Example fix

// before: opening the served HTML directly
curl http://localhost:5173/__cypress/runner  // -> throws in browser console
// after: run through Cypress
cypress run --component --spec src/App.cy.tsx

// browser-side guard
const parent = window.opener || window.parent
if (!(parent && (parent as any).Cypress)) {
  throw new Error('Opened outside Cypress runner; launch via cypress run/open')
}

const hasParentCypress = (w: Window): boolean => !!(w && (w as any).Cypress)

When it happens

Trigger: init(importPromises, parent) runs in the AUT frame and `parent.Cypress` (or window.opener.Cypress) is null. Happens when the spec HTML is loaded outside the Cypress runner context — e.g. opened directly by file:// in a browser, served by a misconfigured dev server that stripped the Cypress injection, or when the parent frame navigated away before init ran.

Common situations: Opening the component runner HTML directly; a custom dev-server setup that bypasses Cypress's window:before:load hook that injects Cypress; an iframe timing race; running webpack-dev-server output outside Cypress.

Related errors

• Unsupported webpackDevServer version ${webpackDevServerMajor
• Unexpected framework ${(devServerConfig as any).framework},
• Failed to load "next/dist/build/webpack-config" with error:
• Unexpected major version of ${json.name}. Cypress webpack-de
• Your Cypress devServer config is missing a required webpackC

AI-assisted analysis of cypress-io/cypress@0d85fdc912 (2026-08-12). Data as JSON: /api/errors/5a1f36d5e3667cad. Report an issue: GitHub.