Debug Error Instant

Paste an error message or stack trace and get an instant diagnosis with root cause analysis, relevant source file locations, and a suggested code fix.

When to Use This Command

Run this command when...

• You have an error message or stack trace and need to quickly understand the root cause
• You want to locate the exact file and line causing the error without manually tracing the call stack
• You need a concrete fix suggestion with code changes you can apply immediately

Avoid this command when...

• The error is deep inside a third-party library and you cannot modify the source
• You need to reproduce the error first and do not yet have a stack trace

Quick Start

Copy
# .claude/commands/debug-error-instant.md
---
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---
Analyze the provided error message or stack trace. Locate the
source file and line. Diagnose the root cause. Suggest a fix.

Example usage:

/debug-error-instant "TypeError: Cannot read properties of undefined (reading 'map') at UserList.tsx:42"

Example output:

Diagnosis: UserList.tsx:42
==========================
Error: TypeError - accessing .map on undefined

Root Cause: The `users` prop is undefined when the component
renders before the API response arrives.

File: src/components/UserList.tsx
Line 42: {users.map(u => <UserCard key={u.id} user={u} />)}

Fix: Add optional chaining or default to empty array:
  {(users ?? []).map(u => <UserCard key={u.id} user={u} />)}

Also consider: Add a loading state in the parent component.

Core Concepts

Concept	Description
Stack trace parsing	Extracts file paths, line numbers, and error types from traces
Source correlation	Reads the actual source file to understand surrounding context
Root cause analysis	Traces the error backward to the originating issue
Fix suggestion	Provides a concrete code change to resolve the error

Error Message --> Parse Stack Trace --> Locate Source Files
                                              |
                                    Read Code Context
                                              |
                                    Identify Root Cause
                                              |
                                    Suggest Fix

Configuration

Option	Default	Description
depth	3	Number of stack frames to analyze in detail
fix	suggest	Fix mode (suggest, apply, diff)
context	10	Lines of source code context around the error line
search-related	true	Look for similar error patterns elsewhere in the codebase
include-docs	false	Search official docs for the error type

Best Practices

1. Paste the full stack trace -- more context leads to a more accurate diagnosis.
2. Include the error message -- just a line number is not enough; the error type drives the root cause analysis.
3. Check the fix before applying -- suggested fixes resolve the immediate error but may not address the underlying design issue.
4. Look for patterns -- if the same error type appears in multiple places, fix the root cause rather than patching each site.
5. Use with runtime errors -- this command excels at TypeError, ReferenceError, and null pointer exceptions.

Common Issues

1. Stack trace from minified code -- source maps are needed to resolve minified references. Ensure source maps are generated in your build.
2. Error in a dependency -- if the root cause is in node_modules, the fix is usually in how you call the library, not in the library itself.
3. Intermittent errors -- race conditions and timing issues may not reproduce consistently. Add logging around the error site to capture state.