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

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. 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:

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 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 ids 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:

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 – Complete validation pipeline including sanitization, normalization, auto-fix, and Zod schemas.
• 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 – Unit tests demonstrating expected good and bad inputs.
• 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 – How validated graphs are loaded into the UI.

Summary

• Call validateGraph() from 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.

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