{"record":{"id":"b74bdf7b04ba5021","repo":"Egonex-AI/Understand-Anything","slug":"a-valid-previous-graph-is-required-for-incremental","errorCode":null,"errorMessage":"A valid previous graph is required for incremental symbol protection","messagePattern":"A valid previous graph is required for incremental symbol protection","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/prepare-incremental.mjs","lineNumber":519,"sourceCode":"  const diffPaths = pathsFromChanges(changes);\n\n  const scanPath = join(intermediateDir, 'scan-result.json');\n  const oldScan = readJson(scanPath, {});\n  const graph = readJson(join(uaDir, 'knowledge-graph.json'), {});\n  const oldFingerprints = normalizeFingerprintStore(\n    readJson(join(uaDir, 'fingerprints.json'), null),\n    baseCommit,\n  );\n  const baselineSnapshotPath = join(intermediateDir, 'incremental-baseline.json');\n  const existingSnapshot = readJson(baselineSnapshotPath, null);\n  const baselineScan = existingSnapshot?.baseCommit === baseCommit\n    ? existingSnapshot.scan\n    : oldScan;\n  const baselineGraph = existingSnapshot?.baseCommit === baseCommit && existingSnapshot.graph\n    ? existingSnapshot.graph\n    : graph;\n  if (!Array.isArray(baselineGraph.nodes) || !Array.isArray(baselineGraph.edges)) {\n    throw new Error('A valid previous graph is required for incremental symbol protection');\n  }\n  if (existingSnapshot?.baseCommit !== baseCommit || !existingSnapshot.graph) {\n    if (graph?.project?.gitCommitHash && graph.project.gitCommitHash !== baseCommit) {\n      throw new Error('Previous graph commit does not match the requested base and no symbol baseline exists; cannot safely retry');\n    }\n    atomicWriteJson(baselineSnapshotPath, { baseCommit, scan: baselineScan, graph: baselineGraph });\n  }\n  // A failed prior attempt can leave complete or split analyzer batches behind.\n  // Remove only known internal scratch names before planning the retry so the\n  // merge cannot resurrect deleted nodes from stale output.\n  clearIncrementalScratch(intermediateDir);\n\n  const currentScanPath = join(intermediateDir, 'current-scan.json');\n  const currentScan = runScan(projectRoot, currentScanPath, args.excludePatterns);\n  const scanFailures = Array.isArray(currentScan?.failures) ? currentScan.failures : [];\n  if (scanFailures.length > 0) {\n    const preview = scanFailures\n      .slice(0, 5)","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/prepare-incremental.mjs#L501-L537","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run a full /understand analysis first so a valid previous graph exists","Delete the corrupt snapshot/graph file (.ua/ baseline snapshot and knowledge-graph.json) and re-run a full analysis","Verify the graph file contains nodes and edges arrays (e.g. with jq '.nodes | type')","Re-run prepare-incremental.mjs with a baseCommit that matches the existing snapshot's baseCommit"],"exampleFix":"// before\nnode prepare-incremental.mjs . HEAD~1   # no previous graph\n// after\n# first produce a valid graph\nunderstand --full\nnode prepare-incremental.mjs . HEAD~1","handlingStrategy":"validation","validationCode":"const graph = JSON.parse(fs.readFileSync('.ua/knowledge-graph.json', 'utf8'));\nif (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {\n  throw new Error('knowledge-graph.json is missing nodes/edges arrays; run a full analysis first');\n}","typeGuard":"function isValidGraph(g) { return Boolean(g) && Array.isArray(g.nodes) && Array.isArray(g.edges); }","tryCatchPattern":"try {\n  await prepareIncremental(args);\n} catch (err) {\n  if (err.message.includes('A valid previous graph is required')) {\n    console.error('No usable baseline; running full analysis instead');\n    return runFullAnalysis();\n  }\n  throw err;\n}","preventionTips":["Always run a full /understand analysis before the first incremental run","Do not hand-edit or truncate .ua/knowledge-graph.json","Validate the graph shape (nodes/edges arrays) after tool version upgrades"],"tags":["graph","state","incremental-analysis"],"backgroundTag":"schema-validation-failed","analyzedSha":"07edf82a04371b6f69779b067bdc8a1a8753a9db","analyzedAt":"2026-09-07T23:20:10.829Z","contentChangedAt":"2026-09-07T23:20:10.829Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}