# How Egonex-AI's Knowledge Graph Validation Works and How to Debug Validation Failures

> Discover how Egonex-AI validates knowledge graphs through its five-stage pipeline & learn to debug validation failures with detailed diagnostic insights. Sanitize, normalize, and auto-fix errors efficiently.

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

---

**Egonex-AI validates every knowledge graph through a five-stage pipeline in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) that sanitizes input, normalizes aliases, auto-fixes recoverable errors, and performs fatal schema checks, returning detailed diagnostic issues for every correction or drop.**

The **Understand-Anything** repository by Egonex-AI implements a robust validation system for knowledge graphs persisted to [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json). Understanding this validation pipeline is essential for debugging why a graph fails to load or why specific nodes and edges disappear during processing.

## The Five-Stage Validation Pipeline

The validation process is deliberately layered to transform malformed input into a clean, well-typed graph while reporting every problem encountered. Each stage is defined in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) and executed sequentially.

### Stage 1: Sanitisation with `sanitizeGraph`

The first stage normalizes trivial inconsistencies that could break downstream processing.

- **Null coalescing**: Converts `null` values to empty arrays
- **Enum normalization**: Lower-cases enum-like strings to ensure consistency
- **Optional field cleanup**: Strips `null` from optional fields

This logic resides at lines 48-71 in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts). The function prepares raw data for stricter schema validation without modifying semantic content.

### Stage 2: Alias Normalisation with `normalizeGraph`

LLM extractors often emit human-friendly aliases rather than canonical enum values. This stage resolves aliases using lookup tables defined in the source code.

- `"func"` → `"function"`
- `"extends"` → `"inherits"`
- `"up"` → `"forward"` (for edge direction)

The alias resolution logic is implemented at lines 68-94 in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts). Using `NODE_TYPE_ALIASES`, `EDGE_TYPE_ALIASES`, and `DIRECTION_ALIASES`, the system maps extractor output to schema-compliant values before validation.

### Stage 3: Auto-Fix with `autoFixGraph`

Before rejecting malformed data, the system attempts automatic recovery. The `autoFixGraph` function supplies missing required fields with sensible defaults and coerces incorrect types.

**Node defaults** (lines 96-150):
- `type: "file"` for nodes missing type information
- `complexity: "medium"` for unlabeled complexity

**Edge defaults** (lines 166-210):
- `direction: "forward"` for edges without direction
- `weight: 1` for unweighted edges (coercing strings to numbers)

Every auto-correction creates an entry in the `issues` array with `level: "auto-corrected"` and includes the `path` to the modified element.

### Stage 4: Fatal Schema Checks with `validateGraph`

The `validateGraph` function performs unrecoverable validation using Zod schemas. If any fatal check fails, the function returns `{ success: false, fatal: "<message>" }` instead of throwing.

**Fatal validation tiers:**

| Tier | Check | Failure Condition | Result |
|------|-------|-------------------|--------|
| 4 | Input type validation | Input is not an object or is `null` | Fatal: "Invalid input: not an object" (lines 100-104) |
| 4 | Collection integrity | `nodes`, `edges`, or other top-level arrays are not arrays | Invalid collection issue (lines 118-124) |
| 4 | Project metadata | Missing `project.name` or `project.languages` | Fatal: "Missing or invalid project metadata" (lines 132-140) |
| 4 | Node existence | No valid nodes remain after validation | Fatal: "No valid nodes found" (lines 158-164) |
| 3 | Node schema (Zod) | Node fails `GraphNodeSchema` validation | Node dropped with `level: "dropped"` issue (lines 144-154) |
| 3 | Edge integrity | Edge fails `GraphEdgeSchema` or references non-existent node IDs | Edge dropped with missing source/target issue (lines 170-202) |
| 3 | Layer/Tour validation | Layer or tour step schema mismatches | Dropped with path-specific issues (lines 210-240) |

**Zod Schema Definitions:**
- `GraphNodeSchema`: lines 68-86
- `GraphEdgeSchema`: lines 88-95  
- `ProjectMetaSchema`, `LayerSchema`, `TourStepSchema`: lines 92-110

When successful, `validateGraph` returns `{ success: true, data: <cleanGraph>, issues: [...] }`.

### Stage 5: Persistence Integration with `loadGraph` and `saveGraph`

The validation pipeline integrates with file operations in [`packages/core/src/persistence/index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/persistence/index.ts).

**Loading** (`loadGraph`):
- Reads [`.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/knowledge-graph.json)
- Unless `options?.validate === false`, invokes `validateGraph`
- Throws an Error containing the fatal message on validation failure (lines 94-100)

**Saving** (`saveGraph`):
- Writes sanitized graphs using `sanitiseFilePaths` to prevent absolute path leakage (lines 38-65)
- Ensures persisted data meets schema requirements before writing

## How to Debug Validation Failures

When a knowledge graph fails validation, the system provides multiple diagnostic layers to identify the root cause.

### Catch Fatal Errors During Loading

Wrap `loadGraph` calls in try/catch blocks to capture fatal validation errors. The error message includes the specific reason from the `validateGraph` fatal check.

```typescript
import { loadGraph } from "@understand-anything/core/persistence";

try {
  const graph = loadGraph("/path/to/project");
  console.log(`Loaded ${graph.nodes.length} nodes`);
} catch (error) {
  console.error("Fatal validation error:", error.message);
  // Output: "Fatal validation error: Missing or invalid project metadata"
}

```

### Inspect the Issues Array for Detailed Diagnostics

For non-fatal problems (dropped nodes, auto-corrected fields), inspect the `issues` array by calling `validateGraph` directly or loading with `validate: false` followed by manual validation.

```typescript
import { validateGraph } from "@understand-anything/core/schema";
import { readFileSync } from "fs";

const raw = JSON.parse(readFileSync("knowledge-graph.json", "utf-8"));
const result = validateGraph(raw);

if (!result.success) {
  console.error("Fatal:", result.fatal);
  process.exit(1);
}

// View all auto-corrections and drops
console.table(result.issues);
// Columns: level, path, message, originalValue

```

Each issue object contains:
- `level`: `"auto-corrected"` or `"dropped"`
- `path`: JSON path to the offending element (e.g., `nodes[5].type`)
- `message`: Human-readable explanation
- `originalValue`: The pre-fix value that caused the issue

### Common Validation Failures and Fixes

**Missing Project Metadata**
Ensure the top-level `project` object includes `name` and `languages` arrays before validation.

**Orphaned Edge References**
Edges referencing non-existent `source` or `target` node IDs are automatically dropped. Verify that all `node.id` values referenced in edges exist in the `nodes` array.

**Invalid Enum Values**
Check that `type`, `complexity`, and `direction` fields use canonical values, not aliases. Refer to the alias tables in [`schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/schema.ts) if preprocessing LLM output.

## Working with Validation Programmatically

### Loading with Default Validation

```typescript
import { loadGraph } from "./packages/core/src/persistence/index.js";

try {
  const graph = loadGraph("/path/to/project");
  console.log("✅ Graph validated:", graph.nodes.length, "nodes");
} catch (err) {
  console.error("🚨 Validation failed:", err.message);
}

```

### Manual Validation for Debugging

```typescript
import { validateGraph } from "./packages/core/src/schema.js";

const result = validateGraph(rawData);
if (!result.success) {
  console.error("Fatal blocker:", result.fatal);
} else {
  console.log("Auto-fixed issues:", result.issues.filter(i => i.level === "auto-corrected").length);
  console.log("Dropped elements:", result.issues.filter(i => i.level === "dropped").length);
}

```

### Skipping Validation for Known-Good Data

```typescript
import { loadGraph } from "./packages/core/src/persistence/index.js";

// Use when data is already validated or for performance
const graph = loadGraph("/path/to/project", { validate: false });
console.log("Loaded without validation:", graph.nodes.length);

```

## Summary

- **Egonex-AI's knowledge graph validation** operates through a five-stage pipeline in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts): sanitisation, alias normalisation, auto-fix, fatal checks, and persistence integration.
- **Sanitisation** handles null values and case normalization, while **alias normalisation** maps LLM-friendly terms to canonical enums like `"function"` and `"inherits"`.
- **Auto-fix** supplies missing defaults (e.g., `type: "file"`, `direction: "forward"`) and logs every correction in the `issues` array with `level: "auto-corrected"`.
- **Fatal checks** use Zod schemas (`GraphNodeSchema`, `GraphEdgeSchema`) to reject malformed input, missing project metadata, or dangling edge references, returning detailed fatal messages.
- **Debugging** involves catching `loadGraph` errors for fatal issues and inspecting the `issues` array for dropped nodes or auto-corrections, using the `path` field to locate specific problems in the JSON structure.

## Frequently Asked Questions

### How do I identify which specific node caused a validation failure?

Inspect the `issues` array returned by `validateGraph`. Each entry includes a `path` property (e.g., `nodes[3].type`) that pinpoints the exact location of the error. For fatal errors thrown by `loadGraph`, you must call `validateGraph` manually on the raw JSON to access the detailed issues list before the exception terminates execution.

### Why are my edges disappearing when I load the knowledge graph?

Edges are dropped when they fail Zod validation or when their `source` or `target` properties reference node IDs that do not exist in the `nodes` array. Check the `issues` array for entries with `level: "dropped"` and `message` containing "missing source" or "missing target" to identify which edges reference non-existent nodes.

### Can I disable automatic fixing and force strict validation?

While you cannot disable auto-fix specifically, you can detect when auto-corrections occur by checking the `issues` array for `level: "auto-corrected"` entries after validation. To prevent loading corrected data, validate the graph manually using `validateGraph` before calling `loadGraph` with `validate: false`, and reject any result containing auto-correction issues.

### What Zod schemas define the knowledge graph structure?

The validation relies on `GraphNodeSchema` (lines 68-86), `GraphEdgeSchema` (lines 88-95), `ProjectMetaSchema`, `LayerSchema`, and `TourStepSchema` (lines 92-110) in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts). These schemas enforce type constraints, required fields, and enum values for all entities in the knowledge graph.