Egonex-AI/Understand-Anything · error

knowledge-graph.json is missing or invalid; baseline not adv

Error message

knowledge-graph.json is missing or invalid; baseline not advanced

What it means

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.

Source

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

  }

  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') {
    const previousGraph = readJson(graphPath);
    if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {
      throw new Error('knowledge-graph.json is missing or invalid; baseline not advanced');
    }
    const refreshedGraph = refreshGraphImports(
      previousGraph,
      scan.importMap ?? {},
      importMapRefreshPaths,
    );
    atomicWriteJson(graphPath, {
      ...refreshedGraph,
      project: projectMetadata(previousGraph.project, plan, scan),
    });
  }

  if (plan.action !== 'SKIP') {
    const previousGraph = readJson(graphPath, {});
    const assembledRaw = readJson(join(intermediateDir, 'assembled-graph.json'));
    if (!assembledRaw || !Array.isArray(assembledRaw.nodes) || !Array.isArray(assembledRaw.edges)) {
      throw new Error('assembled-graph.json is missing or invalid; baseline not advanced');
    }

View on GitHub (pinned to 07edf82a04)

Solutions

1. Run the full /understand pipeline once to produce a valid .ua/knowledge-graph.json, then rerun incremental updates
2. 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)"
3. Check whether a legacy .understand-anything/ directory is being used instead of .ua/ and align on one
4. Restore knowledge-graph.json from version control or a backup if it was accidentally deleted

Example fix

# before: SKIP finalize with no baseline graph
node finalize-incremental.mjs .
# Error: knowledge-graph.json is missing or invalid; baseline not advanced

# after: bootstrap the baseline first
pnpm run understand -- --full   # writes .ua/knowledge-graph.json
node finalize-incremental.mjs .

const graphPath = '.ua/knowledge-graph.json';
if (!fs.existsSync(graphPath)) throw new Error('Run full /understand first');
const g = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
if (!Array.isArray(g.nodes) || !Array.isArray(g.edges)) throw new Error('Invalid baseline graph');

const isValidGraph = (g) =>
  !!g && Array.isArray(g.nodes) && Array.isArray(g.edges);

try {
  await run('node finalize-incremental.mjs .');
} catch (err) {
  if (String(err.message).includes('knowledge-graph.json is missing or invalid')) {
    await runFullUnderstandPipeline();
    await run('node finalize-incremental.mjs .');
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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).

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

• assembled-graph.json is missing or invalid; baseline not adv
• Fingerprint patch does not match the incremental plan commit
• FULL_UPDATE must run the full /understand pipeline
• Assembled graph is missing whole-file nodes for analyzed pat
• Benchmark stage failed: ${stage.name}

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