# 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**: ```bash [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**: ```bash [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**: ```bash [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**: ```bash [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**: - [Theory X]: [Supported/Rejected/Inconclusive] - [New information learned] --- ### Test 2: [Brief Test Description] **Date/Time**: [When] **Theory Being Tested**: [Theory name] **Test Procedure**: ```bash [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**: ```bash [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 ```bash [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**: ```bash [Command to verify the fix] ``` **Verification Result**: ``` [Output showing the error is resolved] ``` **Additional Testing**: - [Test 1]: [Result] - [Test 2]: [Result] --- ## 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]