Invalid input: requires { projectRoot: string, filePaths: st

Error message

Invalid input: requires { projectRoot: string, filePaths: string[], gitCommitHash: string }

What it means

build-fingerprints.mjs validates the fingerprint-input JSON before doing any work: it requires a non-empty `projectRoot` string, an array `filePaths` (also accepting the legacy `sourceFilePaths` key), and a string `gitCommitHash`. If any of these is missing or of the wrong type, it throws this error instead of producing a partially-built or silently-wrong fingerprint baseline.

Source

Thrown at understand-anything-plugin/skills/understand/build-fingerprints.mjs:76

  buildFingerprintStore,
  saveFingerprints,
} = core;

async function main() {
  const [, , inputPath] = process.argv;
  if (!inputPath) {
    process.stderr.write('Usage: node build-fingerprints.mjs <input.json>\n');
    process.exit(1);
  }

  const input = JSON.parse(
    readFileSync(inputPath, 'utf-8'),
  );
  const { projectRoot, gitCommitHash } = input;
  const filePaths = input.filePaths ?? input.sourceFilePaths;

  if (!projectRoot || !Array.isArray(filePaths) || typeof gitCommitHash !== 'string') {
    throw new Error(
      'Invalid input: requires { projectRoot: string, filePaths: string[], gitCommitHash: string }',
    );
  }

  // Create tree-sitter plugin with all configs that have WASM grammars,
  // mirroring extract-structure.mjs so the baseline matches the comparison
  // logic used during auto-updates.
  const tsConfigs = builtinLanguageConfigs.filter((c) => c.treeSitter);
  const tsPlugin = new TreeSitterPlugin(tsConfigs);
  await tsPlugin.init();

  const registry = new PluginRegistry();
  registry.register(tsPlugin);
  registerAllParsers(registry);

  const structuralFingerprintLanguages = new Set(tsConfigs.map(config => config.id));
  const store = buildFingerprintStore(projectRoot, filePaths, registry, gitCommitHash, {
    structuralFingerprintLanguages,

View on GitHub (pinned to 07edf82a04)

Solutions

Open the input JSON passed to build-fingerprints.mjs and ensure it has non-empty `projectRoot`, `gitCommitHash` (string), and `filePaths` (or legacy `sourceFilePaths`) as an array of strings.
If the producer script writes `sourceFilePaths`, verify the array assignment `input.filePaths ?? input.sourceFilePaths` applies — either key is accepted, so the error means one key is absent AND the other is missing/not an array.
Quote shell variables when generating the input so an empty git hash (`git rev-parse HEAD` failure) does not produce null/undefined.
Re-run the upstream extraction/changed-files step so the handoff file is regenerated with the full required shape.

Example fix

// before (input.json)
{ "projectRoot": ".", "filePaths": "src/a.ts src/b.ts" }

// after
{ "projectRoot": "/abs/path/to/project", "filePaths": ["src/a.ts", "src/b.ts"], "gitCommitHash": "abc1234..." }

Defensive patterns

Strategy: validation

Validate before calling

function assertFingerprintInput(input) {
  const filePaths = input.filePaths ?? input.sourceFilePaths;
  if (
    typeof input.projectRoot !== 'string' || !input.projectRoot ||
    !Array.isArray(filePaths) ||
    typeof input.gitCommitHash !== 'string'
  ) {
    throw new Error('fingerprint input requires { projectRoot: string, filePaths: string[], gitCommitHash: string }');
  }
}

Type guard

function isValidFingerprintInput(input) {
  const paths = input.filePaths ?? input.sourceFilePaths;
  return typeof input === 'object' && input !== null &&
    typeof input.projectRoot === 'string' && input.projectRoot.length > 0 &&
    Array.isArray(paths) &&
    typeof input.gitCommitHash === 'string';
}

Try / catch

try {
  await run(['node', 'build-fingerprints.mjs', inputPath]);
} catch (err) {
  if (err.message.includes('Invalid input: requires')) {
    console.error('Fingerprint handoff JSON is malformed:', inputPath);
    // regenerate input via upstream step, then retry once
  } else {
    throw err;
  }
}

Prevention

Generate the handoff JSON with a typed schema (zod/JSON Schema) validated at write time, not hand-written.
Always capture the git hash with `git rev-parse HEAD` and fail the pipeline early if it is empty.
Keep using the `sourceFilePaths` alias consistently — pick one key across all pipeline steps.
Quote shell variables to avoid empty values silently producing null/undefined fields.

When it happens

Trigger: Calling main() of build-fingerprints.mjs with an input JSON that omits any of `projectRoot`, `filePaths`/`sourceFilePaths`, or `gitCommitHash`, or supplies them with wrong types (e.g. relative/empty projectRoot falsy, filePaths as a single string instead of an array, gitCommitHash as a number or null).

Common situations: An incremental handoff step (e.g. /understand-diff) writes the fingerprint input file by hand and forgets `gitCommitHash`; a caller passes `sourceFilePaths` as one comma-joined string; a refactor renamed the field in the producer script but not the consumer; a shell pipeline substitutes an empty value so a key becomes empty string.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/682f34439be162d9. Report an issue: GitHub.