Troubleshooting Common Analysis Errors and Recovery in Understand-Anything

Understand-Anything automatically recovers from common analysis errors through autoFixGraph and sanitizeGraph, which clamp invalid values, drop malformed nodes, and normalize aliases while returning detailed GraphIssue arrays for manual intervention when automatic fixes fail.

Understand-Anything constructs a knowledge graph from your codebase through a pipeline of static analysis, LLM-driven enrichment, and validation. Most errors surface during the validation step in packages/core/src/schema.ts or when the graph is sanitized before persistence in packages/core/src/persistence/index.ts. Understanding how the library handles GraphIssue objects and automatically recovers from schema violations allows you to debug failures without restarting the entire analysis pipeline.

Where Errors Originate in the Analysis Pipeline

The analysis pipeline consists of five distinct phases where errors can occur. Each phase has specific recovery mechanisms built into the source code.

Parsing and Extraction Failures

When file parsers throw exceptions or return malformed nodes, the system handles these gracefully. In packages/core/src/plugins/parsers/*-parser.ts (such as yaml-parser.ts or json-parser.ts), parsers log warnings and fall back to regex-based extractors rather than crashing the entire analysis. This keeps the pipeline alive even when encountering unsupported syntax or corrupted files.

Graph Construction Issues

During graph assembly in packages/core/src/analyzer/graph-builder.ts, the system encounters duplicate IDs and missing required fields. The builder automatically deduplicates IDs and fills missing optional fields with default values, preventing construction failures due to incomplete parser output.

Normalization and Schema Validation

The sanitizeGraph and autoFixGraph functions in packages/core/src/schema.ts handle canonical name mismatches and schema violations. These functions use normalization tables including NODE_TYPE_ALIASES, EDGE_TYPE_ALIASES, COMPLEXITY_ALIASES, and DIRECTION_ALIASES to rewrite aliases and lowercase enum strings before validation runs.

Persistence and Path Sanitization

Before writing to disk, packages/core/src/persistence/index.ts calls sanitiseFilePaths to prevent absolute file paths from leaking user-specific directory structures. The function converts absolute paths to relative paths within the project root, or reduces external paths to just the filename.

The Validation and Auto-Fix Workflow

The validateGraph function in packages/core/src/schema.ts uses Zod schema validation to produce a GraphIssue array. However, the library provides two preprocessing functions that run before or alongside validation to maximize recovery chances.

sanitizeGraph vs autoFixGraph

The sanitizeGraph function performs initial normalization:

• Converts null values to empty arrays []
• Lowercases enum-like strings
• Drops null optional fields

The autoFixGraph function runs after sanitizeGraph and examines each GraphIssue produced by the Zod validator. It performs sensible fixes automatically while returning both the fixed data and an issues array for inspection.

// packages/core/src/schema.ts
export function sanitizeGraph(data: Record<string, unknown>): Record<string, unknown> { … }
export function autoFixGraph(data: Record<string, unknown>): {
  data: Record<string, unknown>;
  issues: GraphIssue[];
} { … }

Automatic Recovery Strategies

The autoFixGraph function handles specific error categories with targeted fixes:

• Out-of-range weights: Values like weight: 1.7 are clamped to 1.0 (or 0.0 for negatives)
• Invalid nodes: Nodes with type: "invalid_type" are dropped from the graph
• Invalid edges: Edges with unrecognized types are dropped while preserving the rest of the graph
• Alias mismatches: Terms like "func" are renamed via NODE_TYPE_ALIASES to "function"
• Missing required fields: If top-level required fields like project are missing, the error is fatal and requires manual correction

If autoFixGraph drops all nodes due to validation failures, it returns a fatal error indicating "No valid nodes," allowing you to inspect the raw node list for systemic issues like misspelled types.

Handling Specific Failure Scenarios

Understanding the symptoms and triggers of common failures helps you apply the correct recovery strategy.

Invalid Knowledge Graph Exceptions

When loadGraph throws an "Invalid knowledge graph" exception, validateGraph has returned success: false with a fatal error. The error bubbles up and aborts dashboard loading. To recover, inspect the issues array returned by autoFixGraph and re-run the analysis, or manually correct the graph JSON in .understand-anything/knowledge-graph.json.

Missing Node Types and Edge Weight Violations

Incomplete parser output can produce nodes with type: undefined, which are automatically dropped with warnings recorded in the issue list. LLM-generated confidence scores exceeding 1.0 (such as weight: 1.7) are automatically clamped to 1.0 with an auto-corrected issue added to the log. These corrections require no manual intervention.

Path Leakage in Persisted Graphs

If you notice absolute file paths in knowledge-graph.json, verify that sanitiseFilePaths is functioning correctly. This function converts absolute paths to relative paths when inside projectRoot, keeps only the basename for external paths, and leaves already-relative paths unchanged. This safeguard prevents secret leakage of user directory structures.

Code Examples for Error Recovery

Running Analysis with Validation Handling

This example demonstrates the complete workflow from analysis through validation to persistence:

import { analyzeProject } from '@understand-anything/core';
import { validateGraph, autoFixGraph } from '@understand-anything/core/schema';

// 1️⃣ Run the analysis pipeline (public CLI entry point)
const rawGraph = await analyzeProject('/path/to/your/project');

// 2️⃣ First pass: sanitize & auto-fix
const { data: fixedGraph, issues } = autoFixGraph(rawGraph);
if (issues.length) {
  console.warn('Analysis produced the following issues:', issues);
}

// 3️⃣ Validate the final graph
const validation = validateGraph(fixedGraph);
if (!validation.success) {
  throw new Error(`Graph is still invalid: ${validation.fatal}`);
}

// 4️⃣ Persist the cleaned graph
import { saveGraph } from '@understand-anything/core/persistence';
saveGraph('/path/to/your/project', validation.data);

Inspecting Issues After Failed Runs

When loading an existing graph fails, inspect the specific issues to determine remediation steps:

import { loadGraph } from '@understand-anything/core/persistence';
import { validateGraph } from '@understand-anything/core/schema';

try {
  const graph = loadGraph('/path/to/project');
  const result = validateGraph(graph!);
  if (!result.success) {
    console.error('Fatal validation error:', result.fatal);
    console.info('Non-fatal issues:', result.issues);
  }
} catch (e) {
  console.error('Unable to load or validate graph:', e);
}

Extending Normalization Aliases

For domain-specific terminology, extend the alias tables before running analysis:

import { NODE_TYPE_ALIASES } from '@understand-anything/core/schema';

// Extend the alias map at runtime (e.g., in a plugin):
NODE_TYPE_ALIASES['svc'] = 'service';
NODE_TYPE_ALIASES['ctrl'] = 'controller';

The alias tables are plain objects; extending them before analysis causes the new aliases to be honored automatically during the sanitizeGraph phase.

Summary

• Automatic recovery occurs through autoFixGraph in packages/core/src/schema.ts, which clamps invalid weights, drops malformed nodes, and normalizes aliases while preserving valid data.
• Path sanitization in packages/core/src/persistence/index.ts prevents directory leakage by converting absolute paths to relative paths or basenames.
• Fatal errors occur only when required top-level fields are missing or when all nodes fail validation; non-fatal issues are automatically corrected and logged.
• Alias customization is possible by extending NODE_TYPE_ALIASES or EDGE_TYPE_ALIASES before running the analysis pipeline.
• Issue inspection is available through the GraphIssue array returned by autoFixGraph, providing specific details about which nodes or edges triggered corrections.

Frequently Asked Questions

What happens when autoFixGraph encounters an invalid node type?

When autoFixGraph encounters a node with an unrecognized type, it drops the node from the graph and adds an invalid-node entry to the GraphIssue array. If all nodes in the graph are invalid, the function returns a fatal error indicating "No valid nodes," requiring you to check the raw node list or add missing aliases to NODE_TYPE_ALIASES.

How does Understand-Anything handle file paths in the persisted knowledge graph?

The sanitiseFilePaths function in packages/core/src/persistence/index.ts processes all file paths before persistence. It converts absolute paths within the project root to relative paths, reduces external absolute paths to just the filename, and leaves already-relative paths unchanged. This prevents user-specific directory structures from leaking into the knowledge-graph.json file.

Can I customize the normalization aliases for domain-specific terminology?

Yes. The normalization tables (NODE_TYPE_ALIASES, EDGE_TYPE_ALIASES, COMPLEXITY_ALIASES, and DIRECTION_ALIASES) exported from packages/core/src/schema.ts are plain JavaScript objects. You can extend them at runtime before calling analyzeProject() to add domain-specific mappings like "svc" to "service" or "ctrl" to "controller".

What is the difference between a fatal and non-fatal GraphIssue?

Non-fatal issues are automatically corrected by autoFixGraph—such as clamping out-of-range weights, dropping invalid edges, or renaming aliases—and the analysis continues with warnings logged. Fatal issues occur when required top-level fields are missing (like the project object) or when all nodes are dropped due to validation failures, causing validateGraph to return success: false and requiring manual intervention to fix the source data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}