# Troubleshooting Common Analysis Errors and Recovery in Understand-Anything

> Learn how to troubleshoot and recover from common analysis errors in Understand-Anything. Discover autoFixGraph and sanitizeGraph for automatic error correction and GraphIssue arrays for manual intervention.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-24

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) or when the graph is sanitized before persistence in [`packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/yaml-parser.ts) or [`json-parser.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.

```typescript
// 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.