Egonex-AI/Understand-Anything · error · Error

Invalid knowledge graph: ${result.fatal ?? "unknown error"}

Error message

Invalid knowledge graph: ${result.fatal ?? "unknown error"}

What it means

Thrown by loadGraph when the on-disk knowledge-graph.json fails schema validation. The function reads .ua/knowledge-graph.json (or the legacy .understand-anything/ variant), parses it, and runs validateGraph; on failure the fatal reason from the validator is interpolated. Validation can be skipped by passing { validate: false }.

Source

Thrown at understand-anything-plugin/packages/core/src/persistence/index.ts:112

    join(dir, GRAPH_FILE),
    JSON.stringify(sanitised, null, 2),
    "utf-8",
  );
}

export function loadGraph(
  projectRoot: string,
  options?: { validate?: boolean },
): KnowledgeGraph | null {
  const filePath = join(resolveUaDir(projectRoot), GRAPH_FILE);
  if (!existsSync(filePath)) return null;

  const data = JSON.parse(readFileSync(filePath, "utf-8"));

  if (options?.validate !== false) {
    const result = validateGraph(data);
    if (!result.success) {
      throw new Error(
        `Invalid knowledge graph: ${result.fatal ?? "unknown error"}`,
      );
    }
    return result.data as KnowledgeGraph;
  }

  return data as KnowledgeGraph;
}

export function saveMeta(projectRoot: string, meta: AnalysisMeta): void {
  const dir = ensureDir(projectRoot);
  writeFileSync(join(dir, META_FILE), JSON.stringify(meta, null, 2), "utf-8");
}

export function loadMeta(projectRoot: string): AnalysisMeta | null {
  const filePath = join(resolveUaDir(projectRoot), META_FILE);
  if (!existsSync(filePath)) return null;
  return JSON.parse(readFileSync(filePath, "utf-8")) as AnalysisMeta;

View on GitHub (pinned to 32944829e7)

Solutions

  1. Re-run the analysis (/understand) to regenerate a schema-conformant knowledge-graph.json.
  2. Call loadGraph(projectRoot, { validate: false }) to read the raw data if you will re-validate or migrate it yourself.
  3. Inspect the fatal message and the full validateGraph issues list to identify which node/project field is wrong, then repair that entry.
  4. Restore knowledge-graph.json from version control or a backup if it was corrupted.

Example fix

// before
const g = loadGraph(projectRoot);
// after — skip validation for a self-managed read, or regenerate
const g = loadGraph(projectRoot, { validate: false });
Defensive patterns

Strategy: validation

Validate before calling

import { validateGraph } from '@understand-anything/core/schema';
import { readFileSync } from 'node:fs';
const raw = JSON.parse(readFileSync(graphPath, 'utf-8'));
const result = validateGraph(raw);
if (!result.success) { /* handle before calling loadGraph */ }

Type guard

import { validateGraph } from '@understand-anything/core/schema';
function isValidGraph(data: unknown): data is KnowledgeGraph {
  return validateGraph(data).success;
}

Try / catch

try { const g = loadGraph(projectRoot); } catch (e) { if (/Invalid knowledge graph/.test(String((e as Error).message))) { /* regenerate or load with validate:false */ } throw e; }

Prevention

When it happens

Trigger: knowledge-graph.json is corrupt or hand-edited; an older graph format written by a prior tool version; validateGraph reports a fatal issue such as 'Invalid input: not an object', 'Missing or invalid project metadata', or 'No valid nodes found in knowledge graph'; a partial write left truncated JSON.

Common situations: Downgrading the tool after a newer graph format was produced; a crashed/killed analysis leaving a half-written file; merging graphs across forks; manual edits to knowledge-graph.json that drop required fields.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/5424c079f6042169. Report an issue: GitHub.