Egonex-AI/Understand-Anything · error

Could not parse ${path}: ${error.message}

Error message

Could not parse ${path}: ${error.message}

What it means

readJson in prepare-incremental.mjs reads a file and parses it as JSON. If the file exists but is not valid JSON (or is not valid UTF-8), the underlying SyntaxError is wrapped as `Could not parse <path>: <message>`. The library treats a malformed state file as fatal rather than silently falling back, because the incremental plan/fingerprint data must be trusted.

Source

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

function isGeneratedArtifact(path) {
  return GENERATED_ROOTS.has(path.split('/')[0]);
}

function isImportResolverConfig(path) {
  const name = path.split('/').at(-1);
  return name === 'tsconfig.json'
    || name === 'go.mod'
    || name === 'composer.json'
    || name === 'Package.swift';
}

function readJson(path, fallback = null) {
  if (!existsSync(path)) return fallback;
  try {
    return JSON.parse(readFileSync(path, 'utf-8'));
  } catch (error) {
    throw new Error(`Could not parse ${path}: ${error.message}`);
  }
}

function atomicWriteJson(path, value) {
  const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
  writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
  renameSync(tempPath, path);
}

function clearIncrementalScratch(intermediateDir) {
  const exactNames = new Set([
    'assembled-graph.json',
    'batch-existing.json',
    'batches.json',
    'layers.json',
    'tour.json',
    'incremental-symbol-report.json',
    'incremental-edge-candidates.json',

View on GitHub (pinned to 07edf82a04)

Solutions

1. Open the path named in the error and fix the JSON syntax error (or restore it from version control/backup); .ua/ artifacts are safe to regenerate, while knowledge-graph.json should be restored from git if tracked.
2. Delete the corrupted state file(s) and re-run the pipeline from the beginning (prepare-incremental.mjs or full /understand) so they are regenerated from scratch.
3. If the whole .ua/ state is suspect, run the full /understand pipeline, which rebuilds knowledge-graph.json and the incremental baseline.
4. Validate the file with a JSON linter (e.g. `node -e "JSON.parse(require('fs').readFileSync('<path>','utf8'))"`) to locate the exact syntax problem.

Example fix

// before: hand-edited knowledge-graph.json left a trailing comma
{ "nodes": [...], "edges": [...], }

// after: remove the trailing comma (or restore from git)
{ "nodes": [...], "edges": [...] }

// pre-check state files before invoking the pipeline
import { readFileSync, existsSync } from 'node:fs';
for (const f of ['.ua/incremental-plan.json', '.ua/knowledge-graph.json'].map(p => join(root, p))) {
  if (existsSync(f)) JSON.parse(readFileSync(f, 'utf-8')); // throws early with position info
}

function isValidJsonFile(path) {
  try { JSON.parse(readFileSync(path, 'utf-8')); return true; }
  catch { return false; }
}

try {
  await prepareIncremental(projectRoot);
} catch (err) {
  const m = /Could not parse (.+?):/.exec(err.message);
  if (m) {
    console.error(`Corrupt state file ${m[1]}; deleting and re-running from scratch.`);
    unlinkSync(m[1]);
    await prepareIncremental(projectRoot);
  } else throw err;
}

When it happens

Trigger: Calling readJson on any .ua/intermediate/ or .ua/ state file (e.g. incremental-plan.json, fingerprint-patch.json, knowledge-graph.json) whose contents are truncated, hand-edited with invalid JSON syntax, corrupted by a crashed non-atomic writer, or saved with an unexpected encoding/BOM.

Common situations: A previous run was killed mid-write before atomicWriteJson's rename completed (legacy writers); the user manually edited knowledge-graph.json and introduced a syntax error; a sync/backup tool truncated the file; the file was written with a UTF-16/BOM encoding that JSON.parse rejects.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• Invalid knowledge graph: ${result.fatal ?? "unknown error"}
• Invalid domain graph: ${result.fatal ?? "unknown error"}
• Benchmark stage failed: ${stage.name}
• JSON changed-file list must be an array of strings
• Fingerprint patch does not match the incremental plan commit

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