Debugging and Troubleshooting Guide for Claude Code

1. Share Error Messages and Stack Traces

When something breaks, the full error message is your best friend. Always share complete error output with Claude Code.

• Copy the entire error stack trace, not just the error message
• Include the context of what you were doing when the error occurred
• Provide file names, line numbers, and the surrounding code
• Include the command/input that triggered the error

2. Minimize the Problem Space

Help Claude Code narrow down the issue by providing minimal reproducible examples:

• Create the smallest possible test case that reproduces the bug
• Remove unrelated code and dependencies
• Focus on the specific function or module causing the issue
• Provide sample input/output that demonstrates the problem

3. Describe Expected vs. Actual Behavior

Be specific about what should happen and what's actually happening:

• Expected: "Function should return an array of 10 items"
• Actual: "Returns an array of 5 items, missing duplicates"
• Expected: "Should execute in under 1 second"
• Actual: "Takes 5+ seconds with large datasets"

4. Use Logging and Debug Output

Before asking Claude Code for help, gather debug information:

• Add console.log() statements to track variable values
• Check log files for error patterns or warnings
• Monitor memory and CPU usage for performance issues
• Use debuggers built into your IDE for deeper inspection

5. Check Configuration and Environment

Many issues stem from configuration problems. Provide context about your setup:

• Node.js / Python version you're using
• Operating system (Mac, Windows, Linux)
• Environment variables and configuration files
• Dependencies and their versions

6. Test Hypotheses Systematically

When debugging, test one thing at a time:

• Ask Claude Code "Could this be caused by [specific issue]?"
• Try the suggested fix and report the result
• If it doesn't work, ask for the next hypothesis
• Document what you've already tried to avoid retesting

7. Leverage Agents for Complex Issues

For bugs that span multiple files or require investigation:

• Use /launch-agent to let Claude explore your codebase
• Agents can search through related files for the root cause
• Great for understanding how different components interact
• Perfect for identifying integration issues

8. Know When to Start Fresh

Sometimes the best debugging approach is simplification:

• Comment out recent changes to identify which broke things
• Use version control to test previous working versions
• Ask Claude Code to refactor the problematic section
• Consider if redesigning the approach would be faster

9. Test Edge Cases

Bugs often hide in edge cases. When debugging, ask about:

• Empty or null inputs
• Very large data sets
• Concurrent operations and race conditions
• Boundary conditions and off-by-one errors
• Special characters and encoding issues

10. Document the Solution

Once fixed, document the issue for future reference:

• Note what caused the bug
• Document the fix and why it works
• Add test cases to prevent regression
• Share the solution if it might help others