Error Navigator Guide

Your agent for diagnosing, understanding, and resolving error messages across programming languages and frameworks — turning cryptic stack traces into clear explanations and actionable fixes.

When to Use This Agent

Choose Error Navigator Guide when:

• Encountering unfamiliar error messages or stack traces
• Debugging compilation, runtime, or build errors
• Understanding framework-specific error codes and messages
• Resolving dependency conflicts, version mismatches, or environment issues
• Diagnosing errors that occur in CI but not locally (or vice versa)

Consider alternatives when:

• You need deep debugging of complex logic bugs — use a debug bot agent
• You need architectural analysis — use an architect agent
• You need to write new code, not fix errors — use a developer agent

Quick Start

Copy
# .claude/agents/error-navigator.yml
name: Error Navigator Guide
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Error diagnosis agent that explains error messages, identifies root causes, and provides actionable fix guidance

Example invocation:

claude "Explain this error and suggest a fix: 'Module not found: Can't resolve '@/components/Header' in '/app/src/pages'"

Core Concepts

Error Classification

Category	Examples	Common Causes
Syntax	SyntaxError, ParseError	Typos, missing brackets, invalid syntax
Type	TypeError, ClassCastException	Wrong type, null access, missing conversion
Reference	ReferenceError, NameError	Undefined variable, wrong import path
Runtime	RuntimeError, OutOfMemoryError	Logic errors, resource exhaustion
Build	CompilationError, BundleError	Missing deps, config issues, incompatible versions
Network	ECONNREFUSED, TimeoutError	Service down, wrong URL, firewall rules

Error Resolution Workflow

1. Read the full error message (including stack trace)
2. Identify the error type and category
3. Locate the originating file and line number
4. Understand the context (what code was running)
5. Identify the root cause (not just the symptom)
6. Apply the fix
7. Verify the error is resolved

Configuration

Parameter	Description	Default
language_context	Primary language for error interpretation	auto-detect
explanation_depth	How detailed the explanation should be	moderate
include_prevention	Suggest how to prevent similar errors	true
search_similar	Search codebase for similar patterns	true
auto_fix	Attempt automatic fix when possible	false

Best Practices

1. Read the entire error message, not just the first line. The most useful information is often in the "Caused by" section or deeper in the stack trace. The top-level error message describes the symptom; the root cause is usually further down.

2. Check the file and line number first. The stack trace points to exactly where the error occurred. Read the code at that location and understand what it was trying to do before searching for solutions online.

3. Compare the error context with working code. Find a similar piece of code in your project that works correctly. The difference between the working code and the broken code often reveals the issue immediately.

4. Search for the exact error message, not a paraphrase. When searching for error messages, use the exact text (with project-specific values removed). "Module not found: Can't resolve" is more useful than "import not working."

5. Fix the root cause, not just the immediate error. Suppressing an error with a try-catch or null check may hide a deeper problem. Understand why the error occurs before deciding how to handle it.

Common Issues

Same error has different root causes in different contexts. "Module not found" could mean a missing dependency, wrong import path, incorrect TypeScript path alias, or misconfigured bundler. Check each possibility systematically rather than assuming the first solution you find is correct.

Error message references internal library code, not your code. When the stack trace points to node_modules or framework internals, look at the last frame that references your code — that's where the problem likely is. Your code is calling the library incorrectly.

Error only appears in production or CI. Environment-specific errors are caused by differences in: Node/Python version, OS (Linux vs macOS), environment variables, file system case sensitivity, or available memory. Compare the environments systematically.