jestjs/jest · error · Error

The --findRelatedTests option requires file paths to be spec

Error message

The --findRelatedTests option requires file paths to be specified.
Example usage: jest --findRelatedTests ./src/source.js ./src/index.js.

What it means

`check` throws (packages/jest-cli/src/args.ts:43) when `--findRelatedTests` is set but no positional file paths were given (`argv._.length === 0`). findRelatedTests works by mapping source file paths to their dependent tests, so without input paths Jest has nothing to query.

Source

Thrown at packages/jest-cli/src/args.ts:44

    'changedSince',
  ]) {
    if (argv[key] && argv.watchAll) {
      throw new Error(
        `Both --${key} and --watchAll were specified, but cannot be used ` +
          'together. Try the --watch option which reruns only tests ' +
          'related to changed files.',
      );
    }
  }

  if (argv.onlyFailures && argv.watchAll) {
    throw new Error(
      'Both --onlyFailures and --watchAll were specified, only one is allowed.',
    );
  }

  if (argv.findRelatedTests && argv._.length === 0) {
    throw new Error(
      'The --findRelatedTests option requires file paths to be specified.\n' +
        'Example usage: jest --findRelatedTests ./src/source.js ' +
        './src/index.js.',
    );
  }

  if (
    Object.prototype.hasOwnProperty.call(argv, 'maxWorkers') &&
    argv.maxWorkers === undefined
  ) {
    throw new Error(
      'The --maxWorkers (-w) option requires a number or string to be specified.\n' +
        'Example usage: jest --maxWorkers 2\n' +
        'Example usage: jest --maxWorkers 50%\n' +
        'Or did you mean --watch?',
    );
  }

View on GitHub (pinned to f49721c78e)

Solutions

Pass the source file paths explicitly: `jest --findRelatedTests ./src/a.js ./src/b.js`.
In a pre-commit hook, guard the call so jest is only invoked when the file list is non-empty (e.g. `if [ -n "$FILES" ]; then jest --findRelatedTests $FILES; fi`).
Use `--listTests --findRelatedTests` first to verify which paths resolve.

Example fix

# before (husky pre-commit)
jest --findRelatedTests $(git diff --cached --name-only)

# after
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx)$')
[ -n "$FILES" ] && jest --findRelatedTests $FILES || echo 'no JS files staged'

Defensive patterns

Strategy: validation

Validate before calling

function ensureRelatedFiles(files: string[]): string[] {
  if (files.length === 0) throw new Error('--findRelatedTests needs at least one file path');
  return files;
}

Type guard

const hasPositionalFiles = (argv: any) => Array.isArray(argv._) && argv._.length > 0;

Prevention

In git hooks, only invoke jest --findRelatedTests when staged JS/TS files exist.
Use lint-staged to pass files only when present.
Add `[ -n "$FILES" ] &&` guards in shell scripts.

When it happens

Trigger: Thrown at packages/jest-cli/src/args.ts:44 when the library encounters an invalid state.

Common situations: Pre-commit hooks where the staged-file list is empty for non-JS commits; shell scripts that build the file list with a glob that expanded to nothing.

Related errors

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/cc31530286d2a0e9.json. Report an issue: GitHub.