jestjs/jest · error · Error

The --findRelatedTests option requires file paths to be…

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() requires that --findRelatedTests be accompanied by at least one positional file path (args.ts:43-49). The flag tells Jest to compute the inverse dependency graph from those source files to their tests; with no files named (argv._.length === 0) there is nothing to relate, so Jest aborts rather than running the whole suite.

Solutions

Pass the source file paths after the flag: jest --findRelatedTests ./src/a.js ./src/b.js.
If automating via lint-staged, use the $eslint etc. variable substitution (e.g. 'jest --findRelatedTests').
Guard the hook so it only invokes jest when at least one file is staged.

Example fix

// before
jest --findRelatedTests
// after
jest --findRelatedTests ./src/source.js ./src/index.js

Defensive patterns

Strategy: validation

Validate before calling

function runFindRelated(files: string[]): void {
  if (files.length === 0) {
    throw new Error('--findRelatedTests needs at least one file path');
  }
  // execa('jest', ['--findRelatedTests', ...files])
}

Type guard

function hasPaths(files: unknown[]): files is string[] {
  return files.length > 0 && files.every(f => typeof f === 'string');
}

Prevention

In lint-staged, pass staged files via the substitution variable so the list is never empty.
Guard pre-commit hooks to skip jest when nothing is staged.
Document the expected invocation in your contributing guide.

When it happens

Trigger: Running jest --findRelatedTests with no trailing paths; a pre-commit hook invoking jest --findRelatedTests before any staged files were passed; a tool that strips positional args before forwarding to jest.

Common situations: husky/lint-staged misconfiguration that calls jest --findRelatedTests without interpolating the staged file list; running the flag manually to try it out; a glob-expansion step that produced zero files.

Related errors

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/cc31530286d2a0e9. Report an issue: GitHub.

Appendix: 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 8e6d128e4a)