Egonex-AI/Understand-Anything · error

Incremental plan or fingerprint patch is missing

Error message

Incremental plan or fingerprint patch is missing

What it means

After resolving the project's data directory, main() reads intermediate/incremental-plan.json and intermediate/fingerprint-patch.json. If either file is missing or unparseable to a truthy object (readJson falls back to null), it throws this error: incremental finalization can only run when the /understand pipeline previously wrote both the plan and the fingerprint patch for the same run.

Source

Thrown at understand-anything-plugin/skills/understand/finalize-incremental.mjs:390

    ...(previousProject ?? {}),
    languages,
    analyzedAt: new Date().toISOString(),
    gitCommitHash: plan.headCommit,
  };
}

async function main() {
  const args = process.argv.slice(2);
  if (args.length !== 1 || args[0].startsWith('--')) {
    throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');
  }
  const projectRoot = realpathSync(args[0]);
  const uaDir = resolveUaDir(projectRoot);
  const intermediateDir = join(uaDir, 'intermediate');
  const plan = readJson(join(intermediateDir, 'incremental-plan.json'));
  const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));
  const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });
  if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');
  if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {
    throw new Error('Fingerprint patch does not match the incremental plan commits');
  }

  if (plan.action === 'FULL_UPDATE') {
    throw new Error('FULL_UPDATE must run the full /understand pipeline');
  }
  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {
    process.stdout.write('Generated artifacts only: analysis baseline unchanged\n');
    return;
  }

  const graphPath = join(uaDir, 'knowledge-graph.json');
  const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)
    ? plan.importMapRefreshPaths
    : [];

  if (plan.action === 'SKIP') {

View on GitHub (pinned to 07edf82a04)

Solutions

1. Run the incremental /understand pipeline first so it writes incremental-plan.json and fingerprint-patch.json into the project data directory's intermediate/ subdirectory, then run the script.
2. Verify the projectRoot passed to the script is the analyzed project (ls <projectRoot>/.ua/intermediate/ to confirm the files exist).
3. If the plan is missing because a FULL_UPDATE was needed, run the full /understand pipeline instead of the incremental finalizer.

Example fix

// before (intermediate artifacts already cleaned up)
node finalize-incremental.mjs .
// after: re-run the pipeline stage that produces the artifacts first
# /understand (incremental)  ->  writes .ua/intermediate/{incremental-plan,fingerprint-patch}.json
node finalize-incremental.mjs .

import { existsSync } from 'node:fs';
import { join } from 'node:path';
const intermediate = join(projectRoot, '.ua', 'intermediate');
if (!existsSync(join(intermediate, 'incremental-plan.json')) || !existsSync(join(intermediate, 'fingerprint-patch.json'))) {
  throw new Error('run the incremental /understand pipeline first');
}

try {
  await runFinalizer(projectRoot);
} catch (err) {
  if (String(err.message).includes('Incremental plan or fingerprint patch is missing')) {
    console.error('No incremental artifacts found; run /understand first or use the full pipeline.');
    process.exit(3);
  }
  throw err;
}

When it happens

Trigger: Running finalize-incremental.mjs against a projectRoot whose .ua/intermediate/ (or .understand-anything/intermediate/) directory lacks incremental-plan.json or fingerprint-patch.json; running it before /understand produced the incremental artifacts; running it after intermediate files were cleaned up; pointing it at the wrong project root.

Common situations: Re-running finalization twice (first run cleans up the intermediate directory); a FULL_UPDATE pipeline run that never wrote a plan; invoking the script manually without having run /understand; a typo'd projectRoot so the script looks in the wrong .ua directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• knowledge-graph.json is missing or invalid; baseline not adv
• assembled-graph.json is missing or invalid; baseline not adv
• Architecture update requires layers.json; baseline not advan
• Architecture update requires tour.json; baseline not advance

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