{"record":{"id":"7b4cf7b164629f3b","repo":"Egonex-AI/Understand-Anything","slug":"knowledge-graph-json-is-missing-or-invalid-baseli","errorCode":null,"errorMessage":"knowledge-graph.json is missing or invalid; baseline not advanced","messagePattern":"knowledge-graph\\.json is missing or invalid; baseline not advanced","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":411,"sourceCode":"  }\n\n  if (plan.action === 'FULL_UPDATE') {\n    throw new Error('FULL_UPDATE must run the full /understand pipeline');\n  }\n  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {\n    process.stdout.write('Generated artifacts only: analysis baseline unchanged\\n');\n    return;\n  }\n\n  const graphPath = join(uaDir, 'knowledge-graph.json');\n  const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)\n    ? plan.importMapRefreshPaths\n    : [];\n\n  if (plan.action === 'SKIP') {\n    const previousGraph = readJson(graphPath);\n    if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {\n      throw new Error('knowledge-graph.json is missing or invalid; baseline not advanced');\n    }\n    const refreshedGraph = refreshGraphImports(\n      previousGraph,\n      scan.importMap ?? {},\n      importMapRefreshPaths,\n    );\n    atomicWriteJson(graphPath, {\n      ...refreshedGraph,\n      project: projectMetadata(previousGraph.project, plan, scan),\n    });\n  }\n\n  if (plan.action !== 'SKIP') {\n    const previousGraph = readJson(graphPath, {});\n    const assembledRaw = readJson(join(intermediateDir, 'assembled-graph.json'));\n    if (!assembledRaw || !Array.isArray(assembledRaw.nodes) || !Array.isArray(assembledRaw.edges)) {\n      throw new Error('assembled-graph.json is missing or invalid; baseline not advanced');\n    }","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L393-L429","documentation":"When the plan action is SKIP, the pipeline still refreshes import metadata in the existing knowledge-graph.json and rewrites it with updated project metadata. If that file is absent or lacks valid nodes/edges arrays, the script throws rather than advancing the baseline, so the next run will retry. This guards against marking analysis as up-to-date when no graph exists.","triggerScenarios":"Running finalize with a SKIP plan but .ua/knowledge-graph.json was deleted, moved, corrupted, or never produced by a prior full run; the graph file exists but its JSON lacks nodes or edges arrays.","commonSituations":"First-ever incremental run on a project with no prior full /understand run; user cleaned .ua/ except intermediate/; an interrupted full run left a truncated knowledge-graph.json; legacy .understand-anything/ directory confusion (reads/writes going to the wrong directory).","solutions":["Run the full /understand pipeline once to produce a valid .ua/knowledge-graph.json, then rerun incremental updates","Validate the graph file exists and contains nodes/edges arrays before finalizing: node -e \"const g=require('./.ua/knowledge-graph.json'); if(!Array.isArray(g.nodes)||!Array.isArray(g.edges)) process.exit(1)\"","Check whether a legacy .understand-anything/ directory is being used instead of .ua/ and align on one","Restore knowledge-graph.json from version control or a backup if it was accidentally deleted"],"exampleFix":"# before: SKIP finalize with no baseline graph\nnode finalize-incremental.mjs .\n# Error: knowledge-graph.json is missing or invalid; baseline not advanced\n\n# after: bootstrap the baseline first\npnpm run understand -- --full   # writes .ua/knowledge-graph.json\nnode finalize-incremental.mjs .","handlingStrategy":"validation","validationCode":"const graphPath = '.ua/knowledge-graph.json';\nif (!fs.existsSync(graphPath)) throw new Error('Run full /understand first');\nconst g = JSON.parse(fs.readFileSync(graphPath, 'utf8'));\nif (!Array.isArray(g.nodes) || !Array.isArray(g.edges)) throw new Error('Invalid baseline graph');","typeGuard":"const isValidGraph = (g) =>\n  !!g && Array.isArray(g.nodes) && Array.isArray(g.edges);","tryCatchPattern":"try {\n  await run('node finalize-incremental.mjs .');\n} catch (err) {\n  if (String(err.message).includes('knowledge-graph.json is missing or invalid')) {\n    await runFullUnderstandPipeline();\n    await run('node finalize-incremental.mjs .');\n  } else throw err;\n}","preventionTips":["Always run a full /understand once before incremental updates","Never delete .ua/knowledge-graph.json while keeping intermediate/","Confirm whether the project uses legacy .understand-anything/ vs .ua/ and stay consistent","Back up the graph file before manual maintenance"],"tags":["incremental","file-not-found","knowledge-graph","pipeline"],"backgroundTag":"file-not-found","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"}