cypress-io/cypress · error · RunSpecError

SPEC_NOT_FOUND

SPEC_NOT_FOUND

Error message

No file exists at path ${specPath}

What it means

Thrown by ProjectActions.runSpec (ProjectActions.ts:548-550) with code SPEC_NOT_FOUND when this.ctx.fs.existsSync(specPath) returns false. It is checked AFTER the testing type is resolved from specPattern but BEFORE any testing-type switch, intentionally so Cypress fails fast instead of switching testing types only to discover the file is missing. distinct from error 67, which checks the loaded-spec list later. Returned as { code: 'SPEC_NOT_FOUND', detailMessage }.

Solutions

1. Verify the file exists at the exact absolute path passed (check case on case-sensitive filesystems).
2. Refresh the spec list in the UI so stale entries are removed before running.
3. Ensure specPath is an absolute, normalized path with no trailing whitespace/slash.
4. If the file was renamed, run the new name; if deleted, remove the dangling reference.

Example fix

// before
await runSpec({ specPath })

// after
if (!fs.existsSync(specPath)) {
  await ctx.actions.refreshSpecs() // or surface 'file missing' to user
  return
}
await runSpec({ specPath })

// Verify the file exists on disk before invoking runSpec
import { existsSync } from 'fs-extra'

if (!existsSync(specPath)) {
  // refresh the spec list or prompt the user; do not call runSpec
  return
}
await ctx.actions.runSpec({ specPath })

When it happens

Trigger: specPath matches a specPattern (so it passes the testing-type resolution) but no file actually exists on disk at that absolute path at run time.

Common situations: Stale spec list in the UI pointing at a file that was deleted/moved/renamed since the list was built; case-sensitivity mismatch on Linux/macOS (MySpec.cy.ts vs myspec.cy.ts); wrong drive or absolute path on Windows; file present in a different working tree; a path with a typo or trailing whitespace.

Related errors

• Could not read ' '.
• Failed generating files
• Failed to update config file
• NO_PROJECT
• NO_SPEC_PATH

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

Appendix: source

Thrown at packages/data-context/src/actions/ProjectActions.ts:549

      // Check to see whether input specPath matches the specPattern for one or the other testing type
      // If it matches neither then we can't run the spec and we should error
      if (await this.ctx.project.matchesSpecPattern(relativeSpecPath, 'e2e')) {
        targetTestingType = 'e2e'
      } else if (await this.ctx.project.matchesSpecPattern(relativeSpecPath, 'component')) {
        targetTestingType = 'component'
      } else {
        throw new RunSpecError('NO_SPEC_PATTERN_MATCH', 'Unable to determine testing type, spec does not match any configured specPattern')
      }

      debug(`Spec %s matches '${targetTestingType}' pattern`, specPath)

      debug('Attempting to launch spec %s', specPath)

      // Look to see if there's actually a file at the target location
      // This helps us avoid switching testingType *then* finding out the spec doesn't exist
      if (!this.ctx.fs.existsSync(specPath)) {
        throw new RunSpecError('SPEC_NOT_FOUND', `No file exists at path ${specPath}`)
      }

      // We now know what testingType we need to be in - if we're already there, great
      // If not, verify that type is configured then switch (or throw an error if not configured)
      if (this.ctx.coreData.currentTestingType !== targetTestingType) {
        if (!this.ctx.lifecycleManager.isTestingTypeConfigured(targetTestingType)) {
          throw new RunSpecError('TESTING_TYPE_NOT_CONFIGURED', `Input path matched specPattern for '${targetTestingType}' testing type, but it is not configured.`)
        }

        debug('Setting testing type to %s', targetTestingType)

        const specChangeSubscription = this.ctx.emitter.subscribeTo('specsChange', { sendInitial: false })

        const originalTestingType = this.ctx.coreData.currentTestingType

        // Temporarily toggle testing type so the `activeBrowser` can be initialized
        // for the targeted testing type. Browser has to be initialized prior to our "relaunch"
        // call below - this can be an issue when Cypress is still on the launchpad and no

View on GitHub (pinned to 0d85fdc912)