6.8 KiB
Debug Session: [Brief Error Summary]
Date: [YYYY-MM-DD] Status: [Active/Resolved/Blocked] Investigator: Claude Error Troubleshooter
Error Information
Error Message
[Paste full error message here, including stack trace if available]
Context
- Command/Tool Executed:
[command or tool that failed] - What Was Being Attempted: [Brief description of the goal]
- When It Failed: [e.g., during build, at runtime, on specific input]
Initial Observations
- [Key observation 1]
- [Key observation 2]
- [Key observation 3]
Environment Information
System
- OS: [e.g., Ubuntu 22.04, macOS 13.1, Windows 11]
- Architecture: [e.g., x86_64, ARM64]
- Shell: [e.g., bash, zsh, PowerShell]
Runtime
- Language/Runtime: [e.g., Python 3.11.0, Node.js 18.12.0]
- Package Manager: [e.g., pip 22.3.1, npm 8.19.2]
- Virtual Environment: [e.g., active venv at /path/to/venv, none]
Dependencies (Relevant Packages)
[package-1]==1.2.3
[package-2]==4.5.6
Configuration (Sanitized)
[Relevant configuration settings, with sensitive data redacted]
Error Template
Extracted Template (for searching):
[Error template with variables removed - see error-template-patterns.md]
Search Queries Used:
[query 1][query 2][query 3]
Research Findings
Source 1: [Stack Overflow / GitHub Issue / Docs / etc.]
URL: [link]
Summary: [Brief summary of relevant information]
Applicability: [High/Medium/Low - how relevant is this to our case?]
Key Quotes/Code:
[Relevant code snippet or quote]
Source 2: [Title]
URL: [link]
Summary: [Brief summary]
Applicability: [High/Medium/Low]
Key Quotes/Code:
[Relevant information]
Source 3: [Title]
URL: [link]
Summary: [Brief summary]
Applicability: [High/Medium/Low]
Theories
Theory 1: [Concise Description]
Likelihood: [High/Medium/Low]
Evidence Supporting:
- [Evidence 1]
- [Evidence 2]
Evidence Against:
- [Counter-evidence 1]
- [Counter-evidence 2]
How to Test:
[Command or approach to verify this theory]
Expected Outcome if Correct: [What would we observe if this theory is correct?]
Expected Outcome if Incorrect: [What would we observe if this theory is wrong?]
Status: [Pending/Testing/Confirmed/Rejected]
Theory 2: [Concise Description]
Likelihood: [High/Medium/Low]
Evidence Supporting:
- [Evidence 1]
- [Evidence 2]
Evidence Against:
- [Counter-evidence 1]
How to Test:
[Command or approach]
Expected Outcome if Correct: [Description]
Expected Outcome if Incorrect: [Description]
Status: [Pending/Testing/Confirmed/Rejected]
Theory 3: [Concise Description]
Likelihood: [High/Medium/Low]
Evidence Supporting:
- [Evidence]
Evidence Against:
- [Counter-evidence]
How to Test:
[Command]
Expected Outcome if Correct: [Description]
Expected Outcome if Incorrect: [Description]
Status: [Pending/Testing/Confirmed/Rejected]
Tests Conducted
Test 1: [Brief Test Description]
Date/Time: [When was this test run]
Theory Being Tested: [Which theory or theories does this test address?]
Test Procedure:
[Exact commands or steps taken]
Expected Result: [What we expected to happen]
Actual Result:
[What actually happened - output, errors, observations]
Analysis: [What does this result tell us? Does it support or reject any theories?]
Conclusion:
- [New information learned]
Test 2: [Brief Test Description]
Date/Time: [When]
Theory Being Tested: [Theory name]
Test Procedure:
[Commands]
Expected Result: [Description]
Actual Result:
[Output]
Analysis: [Interpretation]
Conclusion:
- [What was learned]
Test 3: [Brief Test Description]
Date/Time: [When]
Theory Being Tested: [Theory name]
Test Procedure:
[Commands]
Expected Result: [Description]
Actual Result:
[Output]
Analysis: [Interpretation]
Conclusion:
- [What was learned]
Solution
Root Cause
[Detailed explanation of what was actually causing the error]
Fix Applied
[Exact commands or code changes made to resolve the issue]
Why This Works
[Explanation of why this solution resolves the root cause]
Verification
Verification Command:
[Command to verify the fix]
Verification Result:
[Output showing the error is resolved]
Additional Testing:
Lessons Learned
What Went Well
- [Approach or technique that was effective]
- [Tool or resource that was helpful]
What Could Be Improved
- [Mistake or inefficiency to avoid in future]
- [Better approach that could have been taken]
Key Insights
- [Important insight 1]
- [Important insight 2]
- [Important insight 3]
Applicable to Future Cases
- [General pattern or principle learned]
- [Red flags to watch for in similar errors]
- [Quick checks to try first next time]
References
Documentation
- [Link 1]: [Brief description]
- [Link 2]: [Brief description]
Related Issues
- [Link to similar GitHub issue, Stack Overflow question, etc.]
Tools Used
- [Tool 1]: [What it was used for]
- [Tool 2]: [What it was used for]
Investigation Timeline
[HH:MM] - Investigation started
- Initial error encountered: [brief description]
[HH:MM] - Extracted error template
- Template:
[template]
[HH:MM] - Gathered environment information
- [Key findings]
[HH:MM] - Completed initial research
- [Number] relevant sources found
[HH:MM] - Formulated theories
- [Number] theories developed
[HH:MM] - Began testing
- Started with Theory [N] (highest likelihood)
[HH:MM] - Test 1 completed
- [Result and conclusion]
[HH:MM] - Test 2 completed
- [Result and conclusion]
[HH:MM] - Root cause identified
- [Brief description]
[HH:MM] - Fix applied
- [Brief description]
[HH:MM] - Fix verified
- Error resolved successfully
[HH:MM] - Investigation completed
- Total time: [duration]
Notes
Open Questions
- [Question 1 that remains unanswered]
- [Question 2 that needs clarification]
Future Investigation
- [Area to explore if this error recurs]
- [Related issue to investigate separately]
Blocked By
- [If investigation is blocked, what's blocking it]
- [What needs to happen to unblock]
Metadata
Status: [Active/Resolved/Blocked] Priority: [High/Medium/Low] Tags: [error-type, language, component, etc.] Related Files:
[file1.py][file2.js]Related Errors:- [Link to other debug notes if related]