Egonex-AI/Understand-Anything · error

A valid previous graph is required for incremental symbol pr

Error message

A valid previous graph is required for incremental symbol protection

What it means

main requires a baseline graph with well-formed nodes and edges arrays to protect existing symbols during incremental analysis. The chosen baselineGraph (from a matching prior snapshot, or the previous graph) lacks these arrays, meaning there is no trustworthy previous graph to diff symbols against, so the run aborts to avoid dropping or duplicating symbols.

Source

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

  const diffPaths = pathsFromChanges(changes);

  const scanPath = join(intermediateDir, 'scan-result.json');
  const oldScan = readJson(scanPath, {});
  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)

View on GitHub (pinned to 07edf82a04)

Solutions

1. Run a full /understand analysis first so a valid previous graph exists
2. Delete the corrupt snapshot/graph file (.ua/ baseline snapshot and knowledge-graph.json) and re-run a full analysis
3. Verify the graph file contains nodes and edges arrays (e.g. with jq '.nodes | type')
4. Re-run prepare-incremental.mjs with a baseCommit that matches the existing snapshot's baseCommit

Example fix

// before
node prepare-incremental.mjs . HEAD~1   # no previous graph
// after
# first produce a valid graph
understand --full
node prepare-incremental.mjs . HEAD~1

const graph = JSON.parse(fs.readFileSync('.ua/knowledge-graph.json', 'utf8'));
if (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
  throw new Error('knowledge-graph.json is missing nodes/edges arrays; run a full analysis first');
}

function isValidGraph(g) { return Boolean(g) && Array.isArray(g.nodes) && Array.isArray(g.edges); }

try {
  await prepareIncremental(args);
} catch (err) {
  if (err.message.includes('A valid previous graph is required')) {
    console.error('No usable baseline; running full analysis instead');
    return runFullAnalysis();
  }
  throw err;
}

When it happens

Trigger: existingSnapshot is missing, its baseCommit differs from the requested baseCommit and its graph is absent, or the resolved baselineGraph object has no nodes/edges arrays (corrupt, empty, or hand-edited knowledge-graph.json / snapshot file).

Common situations: First incremental run with no prior full analysis, a corrupted or truncated .ua/knowledge-graph.json, a snapshot written by a different/incompatible tool version, or manually editing the graph file and breaking its shape.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Previous graph commit does not match the requested base and
• Invalid assembled graph
• Architecture update requires layers.json; baseline not advan
• Architecture update requires tour.json; baseline not advance
• Unresolved incremental symbol loss; baseline not advanced

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