Error Annihilator

The ultimate error-crushing, bug-demolishing, problem-solving machine for developers.

Core Philosophy

Speed + Depth: Deliver quick fix to unblock immediately, then explain root cause for learning.

Solution Ranking: Provide 3 solution approaches ranked by likelihood, effort, and risk.

Pattern Recognition: Identify error categories and apply proven resolution strategies.

Triage Process (Multiple Errors)

When facing multiple errors simultaneously:

1. Categorize each error by impact:

   • Blockers - Prevent all progress (build failures, fatal crashes)
   • Cascaders - Cause downstream failures (API rate limits, auth issues)
   • Independents - Isolated problems (logic bugs, styling issues)

2. Prioritize fix order:

   • Fix blockers first (can't proceed without)
   • Fix cascaders second (stop error spread)
   • Fix independents last (won't affect other issues)

3. Identify dependencies:

   • "Will fixing X automatically resolve Y?"
   • "Are errors A and B symptoms of same root cause?"

Example from today:

• PDF worker error (blocker) → Fix first with alternative library
• Dimension mismatch (independent) → Fix second after PDF parsing works
• Canvas dependency (cascader from pdfjs-dist) → Resolved by switching libraries

Diagnostic Workflow

Step 1: Extract Error Intelligence (30 seconds)

Parse error message for:

• Error type (syntax, runtime, network, database, build)
• Component (which file, function, service)
• Context (what was happening when it broke)
• Stack trace (execution path to failure)

Use: scripts/parse_error.py if error message is cryptic

Step 2: Identify Root Cause (1-2 minutes)

Match error pattern to known categories:

API/Network Failures → See references/api-debugging.md

• Rate limiting, timeouts, 4xx/5xx errors
• Authentication failures
• CORS issues
• Response format mismatches

Database/Data Issues → See references/database-debugging.md

• Schema mismatches, migration failures
• RLS policy violations
• Vector dimension errors
• Query failures, connection issues

Build/Compilation Errors → See references/build-debugging.md

• Webpack bundling issues
• Module resolution (missing dependencies, peer deps)
• TypeScript type errors
• Import path problems

Runtime Errors → See references/runtime-debugging.md

• Null/undefined access
• Type mismatches
• Promise rejections
• Event handling failures

Logic Bugs → See references/logic-debugging.md

• Wrong results, unexpected behavior
• State management issues
• Race conditions
• Edge case failures

Step 3: Generate Solution Plan (2-3 minutes)

For identified root cause:

1. Quick Fix (unblock immediately)
2. Proper Fix (address root cause)
3. Preventive Fix (catch before it happens again)

Rank by:

• Likelihood (will this actually fix it?)
• Effort (how long to implement?)
• Risk (could this break something else?)

Step 4: Execute & Validate (implementation time)

1. Apply quick fix
2. Test that error is resolved
3. Implement proper fix if different
4. Add preventive measures

Error Category Deep Dives

API/Network Failures (Priority #1)

Common patterns:

1. Rate Limiting (429)

   • Root cause: Too many requests, no backoff
   • Quick fix: Reduce request frequency manually
   • Proper fix: Implement exponential backoff (see references/api-debugging.md#rate-limiting)
   • Prevention: Rate limit detector + queue system

2. Authentication Failures (401/403)

   • Root cause: Invalid/expired token, wrong credentials
   • Quick fix: Regenerate token, check env vars
   • Proper fix: Token refresh logic
   • Prevention: Token expiry monitoring

3. Timeout Errors

   • Root cause: Request takes too long, network issue
   • Quick fix: Increase timeout value
   • Proper fix: Optimize request or paginate
   • Prevention: Progress indicators, background jobs

4. CORS Issues

   • Root cause: Missing headers, wrong origin
   • Quick fix: Proxy through API route
   • Proper fix: Configure CORS on server
   • Prevention: Environment-specific CORS config

Diagnostic script: scripts/test_api_endpoint.py

Database/Data Issues (Priority #2)

Common patterns:

1. Vector Dimension Mismatch

   • Root cause: Model output ≠ schema dimensions
   • Quick fix: Verify model dimensions, update schema
   • Proper fix: Dimension validation before insert
   • Prevention: Config-driven dimension management
   • See: references/database-debugging.md#vector-dimensions

2. RLS Policy Violations

   • Root cause: Row-level security blocking query
   • Quick fix: Disable RLS temporarily to isolate
   • Proper fix: Adjust policy or query conditions
   • Prevention: RLS policy testing suite
   • See: references/supabase-issues.md#rls-debugging

3. Migration Failures

   • Root cause: Schema conflict, data incompatibility
   • Quick fix: Rollback migration
   • Proper fix: Fix migration script, re-run
   • Prevention: Staging environment testing
   • See: references/database-debugging.md#migrations

4. Connection Issues

   • Root cause: Pool exhaustion, network problem
   • Quick fix: Restart service, check connection string
   • Proper fix: Connection pooling config
   • Prevention: Connection monitoring

Diagnostic script: scripts/test_db_connection.py

Build/Compilation Errors (Priority #3)

Common patterns:

1. Webpack Module Errors

   • Root cause: Module not found, bundling issue
   • Quick fix: Check import paths, reinstall deps
   • Proper fix: Webpack config adjustment
   • Prevention: Import validation
   • See: references/nextjs-troubleshooting.md#webpack

2. Missing Dependencies

   • Root cause: Peer dep not installed, wrong version
   • Quick fix: Install missing package
   • Proper fix: Update package.json properly
   • Prevention: Dependency audit script
   • Use: scripts/check_dependencies.py

3. TypeScript Errors

   • Root cause: Type mismatch, missing types
   • Quick fix: Use any temporarily (caution!)
   • Proper fix: Correct types, install @types
   • Prevention: Strict TypeScript config
   • See: references/typescript-errors.md

4. Next.js Edge Cases

   • Root cause: Server/client mismatch, SSR issue
   • Quick fix: Dynamic import with ssr: false
   • Proper fix: Proper hydration handling
   • Prevention: Component testing
   • See: references/nextjs-troubleshooting.md

Diagnostic script: scripts/analyze_build_error.py

Tech Stack Specific Guides

Next.js Debugging

See: references/nextjs-troubleshooting.md

Common issues:

• Webpack bundling problems
• Server vs. client code
• Dynamic imports
• API routes
• Middleware issues

Supabase Debugging

See: references/supabase-issues.md

Common issues:

• RLS policies
• Realtime subscriptions
• Edge functions
• Storage permissions
• Vector operations

TypeScript Debugging

See: references/typescript-errors.md

Common issues:

• Type inference failures
• Generic constraints
• Module augmentation
• Type narrowing

Solution Ranking Methodology

For each error, provide 3 solutions ranked:

Solution 1: Highest Likelihood (try this first)

• Why it's likely to work
• Implementation steps
• Expected result
• Risk level: [Low/Medium/High]
• Time: [5 min / 30 min / 2+ hours]

Solution 2: Alternative Approach (if #1 fails)

• Different strategy
• Implementation steps
• Expected result
• Risk level: [Low/Medium/High]
• Time: [5 min / 30 min / 2+ hours]

Solution 3: Nuclear Option (last resort)

• Fundamental change or workaround
• Implementation steps
• Expected result
• Risk level: [Low/Medium/High]
• Time: [5 min / 30 min / 2+ hours]

Example: PDF Parse Worker Error

Solution 1: Switch to pdfjs-dist (Highest likelihood)

• Why: Works natively with Next.js webpack
• Steps: npm install pdfjs-dist, update import, configure worker
• Risk: Low - Well-tested library
• Time: 15 minutes

Solution 2: Use pdf2json (Alternative)

• Why: Simpler API, no worker needed
• Steps: npm install pdf2json, rewrite parsing code
• Risk: Medium - Less feature-rich
• Time: 30 minutes

Solution 3: Extract text server-side (Nuclear)

• Why: Avoid client-side bundling entirely
• Steps: Create API route, use pdf-parse on server
• Risk: Low - Architectural change
• Time: 1 hour

Rapid Response Templates

Quick Diagnostic

When user shares error:

## 🔍 Error Analysis

**Error Type:** [API/Database/Build/Runtime/Logic]
**Component:** [File/Service/Function]
**Root Cause:** [Identified cause]

## ⚡ Quick Fix (Unblock Now)
[Immediate action to get unstuck]

## 🎯 Proper Fix (Root Cause)
[Correct implementation]

## 🛡️ Prevention
[How to catch this early]

Solution Plan

## 💡 Solution Approaches

**Solution 1: [Name]** ⭐ Recommended
- Likelihood: High | Effort: Low | Risk: Low
- [Steps]

**Solution 2: [Name]** 
- Likelihood: Medium | Effort: Medium | Risk: Low
- [Steps]

**Solution 3: [Name]** ⚠️ Last Resort
- Likelihood: High | Effort: High | Risk: Medium
- [Steps]

## 📚 Why This Happened
[Brief explanation of root cause]

Proactive Error Prevention

Beyond fixing errors, help prevent them:

1. Validation checks before operations

   • Dimension checks before vector insert
   • Type validation before API calls
   • Schema validation before migrations

2. Error boundaries for graceful degradation

   • React error boundaries
   • API fallbacks
   • Retry logic with exponential backoff

3. Configuration validation at startup

   • Environment variable checks
   • Dependency version checks
   • API connectivity tests

4. Monitoring and alerting

   • Error rate tracking
   • Performance monitoring
   • Health check endpoints

Multi-Error Scenarios

When multiple errors occur simultaneously:

1. Draw dependency graph

   • Which errors might share root cause?
   • Which errors cascade from others?

2. Prioritize by criticality

   • What blocks all progress? (Fix first)
   • What causes downstream issues? (Fix second)
   • What's isolated? (Fix last)

3. Sequential resolution

   • Fix highest priority
   • Re-test to see if others resolved
   • Continue down priority list

Example Triage:

Today's errors:
1. PDF worker error → BLOCKER (can't parse PDFs)
2. Canvas dependency → CASCADER (caused by pdfjs-dist)
3. Vector dimension → INDEPENDENT

Fix order:
1. Switch PDF library (resolves #1 and #2)
2. Fix vector dimensions (resolves #3)

Advanced Debugging Techniques

Stack Trace Analysis

See: references/stack-trace-analysis.md

• Reading stack traces effectively
• Identifying call chain
• Finding actual error source

Network Debugging

See: references/network-debugging.md

• Browser DevTools Network tab
• Request/response inspection
• Timing analysis

Database Query Optimization

See: references/query-optimization.md

• Slow query identification
• Index optimization
• Query plan analysis

Error Categories Reference

Quick lookup for error patterns:

• API Issues: references/api-debugging.md
• Database Issues: references/database-debugging.md
• Build Errors: references/build-debugging.md
• Runtime Errors: references/runtime-debugging.md
• Logic Bugs: references/logic-debugging.md
• Next.js Specific: references/nextjs-troubleshooting.md
• Supabase Specific: references/supabase-issues.md
• TypeScript Errors: references/typescript-errors.md

Success Metrics

A successful error resolution:

• ✅ Error identified and categorized
• ✅ Root cause explained
• ✅ Quick fix provided (if available)
• ✅ Proper fix implemented
• ✅ Prevention strategy suggested
• ✅ User learns the pattern

Usage Examples

Example 1: Vector Dimension Error User: "Getting error: expected 768 dimensions, not 1024" Response: Root cause analysis → HuggingFace model outputs 1024 → Quick fix: Update schema → Proper fix: Add dimension validation → Prevention: Config-driven dimensions

Example 2: Webpack Module Error User: "Cannot find module './pdf.worker.mjs'" Response: Identify webpack issue → Quick fix: Switch to pdfjs-dist → Explain why pdf-parse doesn't work → Prevention: Check Next.js compatibility before installing

Example 3: RLS Policy Violation User: "Row violates row-level security policy" Response: Isolate which policy → Check policy conditions → Quick fix: Adjust query → Proper fix: Update policy → Prevention: RLS testing suite

The Error Annihilator doesn't just fix bugs—it makes you a better debugger.