How to Fix Cypress CI Errors: No Spec Files Found

If Cypress CI reports “No spec files found,” first confirm that the job runs the intended Cypress project and config, then check whether the expected spec paths match the active testing type’s specPattern and are not removed by excludeSpecPattern, --spec, or runtime filters. Keep the default failure when tests are expected. Use --pass-with-no-tests only when an empty selection is an accepted result for that job.

1. Confirm which project and configuration CI uses

Cypress looks for its configuration in the current working directory by default. A CI job can therefore run a different Cypress project than a local command if the app is nested or the workflow step’s working directory differs.

1. Read the CI step’s exact Cypress command and working directory.
2. Check where the intended cypress.config.* file lives.
3. Run from that project directory, or pass the project directory explicitly with --project.
4. Check for command-line configuration overrides. CLI values can override values from the config file.

# From the repository root, target a nested Cypress project
npx cypress run --project apps/storefront

# Or change the CI step's working directory to apps/storefront
npx cypress run

Use the package manager and Cypress invocation your repository already uses. The examples use npx; equivalent project-local commands can be used with npm scripts, pnpm, or Yarn.

2. Check the active testing type and spec pattern

Cypress discovers specs according to the configuration for the testing type being run. The configured specPattern can be a glob or an array of globs. A file that exists in the repository is not necessarily eligible: its path and filename must match the effective pattern for the active type.

Inspect the real path, filename, testing type, and effective config together. For example, if the config pattern only includes cypress/e2e/**/*.cy.ts, a file named cypress/e2e/login.spec.ts will not match it. Update the pattern or move/rename the spec to reflect the project’s convention.

// cypress.config.js — example only; match this to your project
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
    excludeSpecPattern: []
  }
})

Do not assume a historical default applies to your current project. Cypress has had testing-type-specific settings, and defaults or behavior can depend on the installed release and project configuration. Inspect the config and the documentation for the version CI actually installs.

3. Check exclusions and command-line selection

excludeSpecPattern can remove files that otherwise match. Also inspect the CI command for --spec. The command-line selector narrows the candidates; it does not bypass the configured specPattern. A path passed to --spec still has to be eligible under that pattern.

# Select one spec or a glob, provided it also matches specPattern
npx cypress run --spec 'cypress/e2e/login.cy.ts'

# Select several paths or globs
npx cypress run --spec 'cypress/e2e/login.cy.ts,cypress/e2e/cart.cy.ts'

Quote globs so the shell passes the pattern to Cypress rather than expanding it before Cypress receives it. Check that the selected files are tracked and present in the CI checkout, and verify capitalization: case-sensitive CI filesystems can expose a mismatch that a local setup does not.

4. Inspect dynamic test filters

Some workflows apply runtime filtering to choose specs based on branch, environment, tags, or quarantine policy. Those filters can intentionally reduce the candidate set to zero. Trace the value used by the CI job and determine whether an empty result is expected for that branch or job.

• Log or inspect the final filter inputs in CI, such as branch names and tag expressions.
• Compare the filtered selection with the unfiltered candidate set.
• Check whether a workflow matrix entry, conditional, or generated --spec value is empty or points to a nonexistent path.
• Keep discovery failure visible when the filter unexpectedly removes tests.

5. Decide whether zero specs should fail

The key policy question is whether zero specs is valid for this particular job. When the job is supposed to execute tests, fix discovery and retain Cypress’s default failure. That failure tells CI that the intended tests did not run.

When an empty selection is deliberately acceptable—for example, a job intentionally filtered to a set with no applicable specs—Cypress provides --pass-with-no-tests:

npx cypress run --pass-with-no-tests

The option changes the no-spec exit result to success. It is available starting with Cypress 15.11.0; confirm the installed version and current CLI reference before relying on it. Adding the flag to a job that should always run tests can make a broken pattern or filter look successful.

For Cypress Cloud users, note that when no specs are found before recording starts, no recording begins. A successful exit for an intentionally empty run does not mean a test run was recorded.

6. A practical CI diagnostic sequence

1. Print context: inspect the job’s working directory, exact command, Cypress version, and target project path.
2. Verify checkout: confirm the expected spec files exist in the CI workspace with the exact path and capitalization.
3. Read effective settings: inspect the active testing type’s specPattern and excludeSpecPattern, including CLI overrides.
4. Compare selection: check the --spec argument and any dynamic filter against the configured pattern.
5. Classify the result: decide whether this job expects tests or allows zero candidates.
6. Make the matching change: fix project selection or discovery when tests are expected; add --pass-with-no-tests only for an intentionally empty selection.
7. Recheck after upgrades: if the paths and patterns appear correct, compare the installed release with current documentation and changelog entries for filtering or glob/path handling changes.

Common errors and fixes

Symptom	Likely cause	Fix
Specs exist locally, but CI finds none	CI runs from the repository root or a different directory, so it loads a different project/config.	Set the step’s working directory or pass --project for the intended project.
--spec names a real file, but Cypress still finds none	The file does not also match the active testing type’s specPattern, or an exclusion removes it.	Align the path and pattern, then review excludeSpecPattern.
Only some expected specs run	The CLI glob, pattern, exclusion, or runtime filter narrows the set.	Inspect each selection layer and compare the result with the expected file list.
A pattern works on a laptop but not in CI	Path capitalization differs, files are missing from the checkout, or shell glob expansion changes the argument.	Check exact casing and checkout contents; quote the glob passed to Cypress.
--pass-with-no-tests is unrecognized	The installed Cypress version predates support for the flag.	Verify the version in CI and consult its version-specific CLI documentation; the option starts with 15.11.0.
The job passes, but no Cypress Cloud run appears	No specs were found before Cypress Cloud recording began.	Confirm whether zero specs is intentional; successful no-spec exit does not create a recording in that case.

Reliability, performance, and cost considerations

Spec discovery is a correctness gate: a green job is useful only if the job ran the tests it was meant to run. Keep unexpected empty selections as failures, and make intentionally empty jobs explicit in their command or workflow policy. This makes an empty run distinguishable from a run that actually executed tests.

Discovery itself is governed by project location, patterns, exclusions, and filters. If an apparently valid setup changes behavior after a Cypress upgrade, inspect release-specific documentation and the changelog before broadening patterns or suppressing the exit code. Broad patterns can admit files the job did not intend to execute, while overly narrow patterns can silently leave intended files out of the eligible set.

The dossier provides no benchmark or quantified cost impact for this error. In practical CI terms, an empty successful job can waste the CI run’s allocated time while providing no test coverage; fixing selection or explicitly classifying the empty case avoids treating that run as evidence that tests passed.

Or skip the browser setup

If you need a screenshot while investigating a page’s visual state, ScreenshotNeo offers a one-request website screenshot API and MCP server. It is separate from Cypress spec discovery and does not fix a Cypress configuration error. The API can return PNG, JPEG, WebP, or PDF; its documented parameters and options are in the ScreenshotNeo API docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

• Cookie banners and consent prompts are accepted before capture; 60+ known consent platforms, newsletter popups, and chat widgets are removed. Each step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses identify the page verdict and billing status with headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
• The free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

Learn about ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.

FAQ

Does --spec override specPattern?

No. A selected path must also match the configured pattern for the active testing type.

Should every CI job use --pass-with-no-tests?

No. Use it only when that job accepts zero selected specs. Otherwise, the default failure is an important signal that expected tests did not run.

What should I check if everything looks correct?

Confirm the installed Cypress version in CI and compare its behavior with the versioned documentation and changelog, especially entries related to filtering and path or glob handling.

Sources

• Cypress CLI commands and options
• Cypress: Fix Cypress CI failures caused by no spec files found
• Cypress App changelog
• Cypress issue: Opt-in functionality to not fail if no spec files found