Previous graph commit does not match the requested base and

Error message

Previous graph commit does not match the requested base and no symbol baseline exists; cannot safely retry

What it means

When the existing snapshot's baseCommit does not match the requested baseCommit (or no snapshot graph exists), main falls back to using the graph produced in this run as the baseline. If that graph records a gitCommitHash different from the requested baseCommit, there is no symbol baseline for the requested base, and retrying incrementally could silently protect symbols against the wrong revision — so it refuses.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-incremental.mjs:523

  const graph = readJson(join(uaDir, 'knowledge-graph.json'), {});
  const oldFingerprints = normalizeFingerprintStore(
    readJson(join(uaDir, 'fingerprints.json'), null),
    baseCommit,
  );
  const baselineSnapshotPath = join(intermediateDir, 'incremental-baseline.json');
  const existingSnapshot = readJson(baselineSnapshotPath, null);
  const baselineScan = existingSnapshot?.baseCommit === baseCommit
    ? existingSnapshot.scan
    : oldScan;
  const baselineGraph = existingSnapshot?.baseCommit === baseCommit && existingSnapshot.graph
    ? existingSnapshot.graph
    : graph;
  if (!Array.isArray(baselineGraph.nodes) || !Array.isArray(baselineGraph.edges)) {
    throw new Error('A valid previous graph is required for incremental symbol protection');
  }
  if (existingSnapshot?.baseCommit !== baseCommit || !existingSnapshot.graph) {
    if (graph?.project?.gitCommitHash && graph.project.gitCommitHash !== baseCommit) {
      throw new Error('Previous graph commit does not match the requested base and no symbol baseline exists; cannot safely retry');
    }
    atomicWriteJson(baselineSnapshotPath, { baseCommit, scan: baselineScan, graph: baselineGraph });
  }
  // A failed prior attempt can leave complete or split analyzer batches behind.
  // Remove only known internal scratch names before planning the retry so the
  // merge cannot resurrect deleted nodes from stale output.
  clearIncrementalScratch(intermediateDir);

  const currentScanPath = join(intermediateDir, 'current-scan.json');
  const currentScan = runScan(projectRoot, currentScanPath, args.excludePatterns);
  const scanFailures = Array.isArray(currentScan?.failures) ? currentScan.failures : [];
  if (scanFailures.length > 0) {
    const preview = scanFailures
      .slice(0, 5)
      .map(failure => `${failure.path ?? '<global>'} (${failure.stage})`)
      .join(', ');
    const suffix = scanFailures.length > 5 ? ` (+${scanFailures.length - 5} more)` : '';
    throw new Error(`Project scan reported failures: ${preview}${suffix}`);

View on GitHub (pinned to 07edf82a04)

Solutions

Pass the baseCommit that matches the previous analysis: read .ua snapshot's baseCommit and use it
Re-run a full /understand analysis at the desired base commit to regenerate a matching graph, then retry incremental
Update the repo so HEAD/gitCommitHash matches the requested baseCommit (git checkout <baseCommit>)
Delete stale snapshot files under .ua/ and rebuild from a full analysis if the history was rewritten (rebase/reset)

Example fix

// before
node prepare-incremental.mjs . abc1234   # graph built at different commit
// after
# rebuild the baseline at the requested commit
git checkout abc1234
understand --full
node prepare-incremental.mjs . abc1234

Defensive patterns

Strategy: validation

Validate before calling

const snapshot = JSON.parse(fs.readFileSync('.ua/base-snapshot.json', 'utf8'));
const graph = JSON.parse(fs.readFileSync('.ua/knowledge-graph.json', 'utf8'));
if (snapshot.baseCommit !== requestedBase || graph?.project?.gitCommitHash !== requestedBase) {
  console.error('Baseline commit mismatch; run a full analysis at the requested base first');
}

Type guard

function baselineMatches(snapshot, graph, base) {
  return snapshot?.baseCommit === base &&
    (!graph?.project?.gitCommitHash || graph.project.gitCommitHash === base);
}

Try / catch

try {
  await prepareIncremental(args);
} catch (err) {
  if (err.message.includes('cannot safely retry')) {
    console.error('Rebuilding baseline with full analysis at the requested commit');
    return runFullAnalysis(base);
  }
  throw err;
}

Prevention

Always pass the same baseCommit the previous full analysis was built at
Avoid rebases/resets that move HEAD after generating the graph, or rebuild the graph afterwards
Check graph.project.gitCommitHash against your intended baseCommit before incremental runs

When it happens

Trigger: existingSnapshot.baseCommit !== baseCommit and the freshly produced graph.project.gitCommitHash differs from the requested baseCommit — e.g. passing a baseCommit other than the one the previous full analysis was built from, or HEAD moved between graph generation and this run.

Common situations: Requesting an older baseCommit than the last full analysis used, a rebase/reset changing HEAD after the graph was built, or a stale .ua/knowledge-graph.json generated at a different commit.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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