cypress-io/cypress · error · RunSpecError

NO_SPEC_PATH

NO_SPEC_PATH

Error message

`specPath` must be a non-empty string

What it means

Thrown by ProjectActions.runSpec (ProjectActions.ts:523-525) with code NO_SPEC_PATH when the specPath argument is falsy (empty string, undefined, null). It is the second guard in runSpec, checked right after the project-open guard. Like the other RunSpecErrors it is caught by the surrounding try/catch and returned as { code: 'NO_SPEC_PATH', detailMessage }.

Source

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

          new Promise((resolve) => setTimeout(resolve, 1000)),
          browserStatusSubscription.next(),
        ])

        if (--maxIterations === 0) {
          break
        }
      }

      await browserStatusSubscription.return(undefined as any)
    }

    try {
      if (!this.ctx.currentProject) {
        throw new RunSpecError('NO_PROJECT', 'A project must be open prior to attempting to run a spec')
      }

      if (!specPath) {
        throw new RunSpecError('NO_SPEC_PATH', '`specPath` must be a non-empty string')
      }

      let targetTestingType: TestingType

      // Get relative path from the specPath to determine which testing type from the specPattern
      const relativeSpecPath = path.relative(this.ctx.currentProject, specPath)

      // 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)

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Validate specPath is a non-empty string before calling runSpec and skip/throw early in the caller.
2. In the UI, ensure a spec is selected (non-null) before enabling the run action.
3. Use the dedicated 'run all specs' path (RUN_ALL_SPECS) rather than passing an empty specPath to runSpec.

Example fix

// before
await runSpec({ specPath: maybePath })

// after
if (typeof specPath !== 'string' || specPath.trim().length === 0) {
  throw new Error('specPath must be a non-empty string')
}
await runSpec({ specPath })

// Validate specPath before calling runSpec
function isValidSpecPath(specPath: unknown): specPath is string {
  return typeof specPath === 'string' && specPath.trim().length > 0
}

if (!isValidSpecPath(specPath)) {
  throw new Error('A non-empty specPath is required')
}
await ctx.actions.runSpec({ specPath })

function isNonEmptyString(value: unknown): value is string {
  return typeof value === 'string' && value.length > 0
}

// narrowing
if (!isNonEmptyString(specPath)) {
  // caller bug: do not invoke runSpec
}

When it happens

Trigger: Invoking runSpec({ specPath }) with an empty string, undefined, or null — e.g. a 'run all specs' request with no individual path, a UI event where no spec was selected, or a null leaking from a spec-list lookup.

Common situations: Clicking run before selecting a spec; a stale/null spec reference passed from the UI; calling the runSpec GraphQL mutation without a specPath argument; programmatic automation that assumes a spec is always selected.

Related errors

• Invalid project path parameter: ${options.project}
• Unknown component name "${componentName}"
• No file name specified. This is required to generate a new C
• Invalid grep burn value: ${grepBurn}
• ESM plugin config value '${name}' must be an array of string

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