# How to Debug Graph Validation Failures and Schema Errors in Understand-Anything

> Debug graph validation failures and schema errors in Understand Anything using validateGraph(). Inspect ValidationResult issues to identify and fix fatal errors.

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

---

**Call `validateGraph()` on your raw graph object and inspect the returned `ValidationResult`, paying special attention to `issues` with `level: "fatal"` and verifying that auto-corrected fields match your expectations.**

The Understand-Anything library constructs knowledge graphs from codebases and validates them against strict Zod schemas defined in [`understand-anything-plugin/packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/schema.ts). When validation fails, the system returns a detailed diagnostic object that pinpoints exactly where data diverges from the expected structure, including auto-corrected fields and dropped entities.

## Understanding the Validation Pipeline

The validation logic runs in four distinct stages before returning a final result. Understanding these stages helps you interpret the error messages and `GraphIssue` objects correctly.

### The Four Stages of Processing

1. **Sanitization** – Normalizes `null` values and case issues. For example, the sanitizer converts `null` to empty arrays (`[]`) for the `tour` and `layers` collections at lines 52-54.
2. **Normalization** – Maps LLM-generated aliases to canonical node and edge types using lookup tables defined at lines 16-78.
3. **Auto-fix** – Fills missing required fields and coerces values (e.g., string to number) through the `autoFixGraph` function spanning lines 196-502.
4. **Structural validation** – Performs final schema checks including referential integrity and top-level collection types at lines 1000-1030.

### The ValidationResult Object

When you call `validateGraph(rawGraph)`, you receive a `ValidationResult` object defined around line 331 containing:

- **`success`** – Boolean indicating overall pass/fail status.
- **`issues`** – Array of `GraphIssue` objects describing every problem encountered, including auto-corrected and dropped items.
- **`errors`** – Human-readable message strings derived from the issues array.
- **`data`** – The sanitized, normalized, and auto-fixed graph that passed through the pipeline, even if validation ultimately failed.

## Step-by-Step Debugging Workflow

Follow this systematic approach to diagnose validation failures using the actual source implementation.

### 1. Run the Validator and Capture Output

Call `validateGraph()` starting at line 998 and store the result:

```typescript
import { validateGraph, type ValidationResult } from '@understand-anything/core/schema';

const result: ValidationResult = validateGraph(rawGraph);

```

### 2. Examine the Issues Array

Each `GraphIssue` in `result.issues` tells you *where* the problem occurred via the `path` property, *what* category it belongs to via `category`, and the severity via `level`.

### 3. Identify Fatal Problems

Check for any issue with `level: "fatal"`. These terminate the pipeline and prevent graph usage. Fatal checks occur at lines 1000-1030 (object type validation) and lines 1018-1030 (top-level collection type validation). Common fatal errors include non-object inputs, missing project metadata, or collections that are not arrays.

### 4. Review Auto-Corrected Entries

Look for issues marked as auto-corrected. These indicate fields that were missing or malformed but have been filled with defaults—for example, a missing node `type` being set to `"file"`. The auto-fix logic lives in `autoFixGraph` (lines 196-502). Compare `result.data` against your original input to understand what defaults were injected.

### 5. Check Dropped Nodes and Edges

Items removed from the graph appear as issues with drop reasons. The dropping logic executes in the node validation loop (lines 444-560) and edge validation loop (lines 572-608). Dropped edges typically reference non-existent node IDs, while dropped nodes fail schema validation for required fields like `id`, `type`, `name`, `summary`, `tags`, or `complexity`.

### 6. Verify Alias Normalization

LLMs often emit aliases like `"func"` or `"extends"` instead of canonical types. The `normalizeGraph` step (lines 622-696) rewrites these using `NODE_TYPE_ALIASES` and `EDGE_TYPE_ALIASES`. If an alias is missing from the maps declared at lines 16-78, it remains unchanged and causes subsequent validation errors.

### 7. Use Console Logging or Unit Tests

Insert temporary `console.log` statements after specific stages (e.g., after `sanitizeGraph`) or write unit tests in [`__tests__/schema.test.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/__tests__/schema.test.ts) to isolate failures with minimal reproducing graphs.

## Common Failure Patterns and Fixes

| Symptom | Root Cause | Solution |
|---------|------------|----------|
| **"Missing or invalid project metadata"** | `ProjectMetaSchema` validation failed (lines 612-618) due to missing `name` or `languages` fields. | Add the required keys to the top-level `project` object. |
| **"nodes[12]: invalid-node"** | Node missing required fields defined in the schema. | Provide `id`, `type`, `name`, `summary`, `tags`, and `complexity`, or let `autoFixGraph` populate defaults. |
| **"edges[7]: source 'foo' does not exist in nodes"** | Edge references a non-existent node ID. | Ensure both `source` and `target` values match actual node `id`s present in the graph. |
| **"edges[3]: direction 'outbound' – mapped to 'forward'"** | Alias normalization via `DIRECTION_ALIASES`. | No action needed; the canonical value is already applied. |
| **"Invalid collection: layers"** | `layers` field is not an array (e.g., `null` or object). | Change to an empty array `[]` if no layers exist. |

## Practical Debugging Example

Use this pattern to inspect validation results programmatically:

```typescript
import { validateGraph, type ValidationResult } from '@understand-anything/core/schema';

const raw = JSON.parse(await Deno.readTextFile('knowledge-graph.json'));
const result: ValidationResult = validateGraph(raw);

if (!result.success) {
  console.error('❌ Graph validation failed');
  
  if (result.errors) {
    console.error(result.errors.join('\n'));
  }

  result.issues.forEach((issue) => {
    console.warn(`[${issue.level}] ${issue.category}: ${issue.message}`);
    if (issue.path) {
      console.warn(`  ↳ Path: ${issue.path}`);
    }
  });

  if (result.data) {
    console.log('Auto-fixed graph nodes:', result.data.nodes.length);
    console.log('Auto-fixed graph edges:', result.data.edges.length);
  }
} else {
  console.log('✅ Graph is valid and ready for dashboard rendering.');
}

```

## Key Source Files for Deep Diving

- **[`understand-anything-plugin/packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/schema.ts)** – Complete validation pipeline including sanitization, normalization, auto-fix, and Zod schemas.
- **[`understand-anything-plugin/packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/types.ts)** – TypeScript definitions for nodes, edges, layers, and tours.
- **[`understand-anything-plugin/packages/core/__tests__/schema.test.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/__tests__/schema.test.ts)** – Unit tests demonstrating expected good and bad inputs.
- **[`understand-anything-plugin/packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/graph-builder.ts)** – Where graphs are initially assembled before validation.
- **[`understand-anything-plugin/packages/core/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/store.ts)** – How validated graphs are loaded into the UI.

## Summary

- **Call `validateGraph()`** from [`understand-anything-plugin/packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/schema.ts) to trigger the four-stage validation pipeline.
- **Inspect `result.issues`** for `GraphIssue` objects containing `path`, `category`, and `level` properties.
- **Treat `level: "fatal"` errors** as blocking issues that must be resolved before the graph can be used.
- **Review auto-corrected entries** in `result.data` to understand what defaults were injected by `autoFixGraph` (lines 196-502).
- **Verify edge references** point to existing node IDs to prevent items from being dropped in the validation loops (lines 444-608).
- **Check alias mappings** at lines 16-78 if node or edge types are not normalizing as expected.

## Frequently Asked Questions

### What does a "fatal" validation level indicate?

A fatal issue means the graph cannot be used in its current state. According to the source code at lines 1000-1030, fatal errors occur when the input is not a valid object, when project metadata is missing, or when top-level collections like `nodes` or `edges` are not arrays. These errors halt the pipeline before auto-fixing can complete.

### How do auto-corrected issues affect my graph data?

Auto-corrected issues indicate that `autoFixGraph` (lines 196-502) filled missing required fields with default values. For example, a missing `type` field becomes `"file"`, and malformed complexity scores may be coerced to numbers. The corrected graph is available in `result.data`, but you should verify these defaults match your domain requirements.

### Why are my edges being dropped during validation?

Edges are dropped in the validation loop at lines 572-608 when they fail schema validation or when their `source` or `target` properties reference node IDs that do not exist in the graph. Ensure all referenced nodes are present and have valid `id` fields before calling `validateGraph()`.

### How do I fix schema errors related to LLM-generated aliases?

The `normalizeGraph` function (lines 622-696) maps aliases like `"func"` to canonical types using lookup tables declared at lines 16-78. If your LLM outputs an unrecognized alias not defined in `NODE_TYPE_ALIASES` or `EDGE_TYPE_ALIASES`, add it to these maps or pre-process your data to use canonical values before validation.