Troubleshooting

Common issues and solutions for using debtmap effectively.

Getting Started with Troubleshooting

When you encounter an issue with debtmap, start with these steps:

1. Try a quick fix - See Quick Fixes for common problems and immediate solutions
2. Enable debug mode - Use -v, -vv, or -vvv for increasing levels of detail
3. Check error messages - See Error Messages Reference for explanations
4. Review your configuration - Check .debtmap/config.toml for any settings that might cause issues

Subsections

This chapter is organized into focused troubleshooting topics:

• Quick Fixes - Common problems with immediate solutions
• Debug Mode - Verbosity levels and diagnostic options
• Context Provider Issues - Troubleshooting critical_path, dependency, and git_history providers
• Advanced Analysis Issues - Call graph, pattern detection, functional analysis issues
• Error Messages Reference - Detailed error message explanations
• Output and Command Issues - Output formatting and command-specific problems
• FAQ - Frequently asked questions

Common Problem Categories

Analysis Problems

• Slow analysis: See Quick Fixes or Debug Mode
• Parse errors: See Quick Fixes or Error Messages Reference
• No output: See Quick Fixes
• Inconsistent results: See Quick Fixes

Coverage and Context Problems

• Coverage not applied: See Quick Fixes
• Context provider errors: See Context Provider Issues

Output Problems

• JSON parsing issues: See Quick Fixes or Output and Command Issues
• Compare command errors: See Output and Command Issues

Detection Problems

• God object false positives: See Quick Fixes or Advanced Analysis Issues
• Pattern detection issues: See Advanced Analysis Issues
• Call graph problems: See Quick Fixes or Advanced Analysis Issues

Diagnostic Commands

Basic Diagnostics

# Check version
debtmap --version

# Run with basic verbosity
debtmap analyze . -v

# Run with detailed output
debtmap analyze . -vv

# Run with full debug output
debtmap analyze . -vvv

Coverage Diagnostics

# Debug coverage matching for a function
debtmap explain-coverage . \
  --coverage-file coverage.lcov \
  --function "function_name" \
  -v

Performance Diagnostics

# Time the analysis
time debtmap analyze .

# Profile with verbosity
debtmap analyze . -vv 2>&1 | grep "processed in"

When to File Bug Reports

File a bug report when:

• Parse errors on valid syntax
• Crashes or panics
• Incorrect complexity calculations
• Concurrency errors
• Incorrect error messages

Before filing:

1. Check this troubleshooting guide
2. Try --semantic-off fallback mode
3. Update to the latest version
4. Search existing issues on GitHub

See FAQ for detailed guidance.

Related Documentation

• Configuration - Configure debtmap behavior
• CLI Reference - Complete CLI flag documentation
• Analysis Guide - Understanding analysis results
• Examples - Practical usage examples