Debugging Rubric - Failure Pattern Taxonomy

Debugging Rubric - Failure Pattern Taxonomy

Reference for identifying and resolving common failure patterns in web applications.

Severity Levels

Failure Categories

1. Authentication Failures

Symptoms

• 401 Unauthorized responses
• Sudden logout
• "Session expired" errors
• Redirect loops to login page

Common Causes

Log Patterns

# Azure/Backend
"Authentication failed" | "Invalid token" | "Token expired"
"JWT decode error" | "Signature verification failed"

# Frontend Console
"401" | "Unauthorized" | "clearToken" | "logout"

Diagnostic Steps

1. Check if token exists in request headers
2. Verify token hasn't expired (decode JWT, check exp)
3. Check for redirect responses (307/308) losing headers
4. Verify CORS allows Authorization header

2. Network/Connectivity Failures

Symptoms

• Connection refused
• Timeout errors
• CORS errors
• WebSocket disconnection

Common Causes

Log Patterns

# Azure/Backend
"Connection refused" | "ETIMEDOUT" | "ECONNRESET"
"Max retries exceeded" | "Connection pool exhausted"

# Frontend Console
"Failed to fetch" | "NetworkError" | "CORS" | "blocked"
"WebSocket connection failed" | "wss://" | "ws://"

Diagnostic Steps

1. Check service health endpoints directly
2. Verify DNS resolution
3. Check firewall/security group rules
4. Verify WebSocket URL isn't falling back to localhost

3. Configuration/Environment Failures

Symptoms

• Feature works locally but not in staging/prod
• Requests going to wrong URL
• Missing environment variable errors
• Fallback to localhost URLs

Common Causes

Log Patterns

# Azure/Backend
"KeyError" | "Missing environment variable" | "Config not found"
"undefined" (in URL construction)

# Frontend Console
"localhost:3000" | "localhost:8000" (in production!)
"undefined" | "null" (in API calls)

Diagnostic Steps

1. Check Network tab for localhost URLs
2. Grep code for fallback patterns: || 'http://localhost'
3. Verify env vars are set: printenv | grep NEXT_PUBLIC
4. Check for undefined in URL construction

4. Data/State Failures

Symptoms

• Stale data displayed
• "Cannot read property of undefined"
• Type errors in data processing
• Empty lists when data expected

Common Causes

Log Patterns

# Backend
"TypeError" | "KeyError" | "AttributeError"
"NoneType has no attribute" | "undefined is not a function"

# Frontend Console
"Cannot read property" | "undefined" | "null"
"TypeError: x is not a function"

Diagnostic Steps

1. Check API response shape in Network tab
2. Verify TypeScript types match API
3. Add console.log before error point
4. Check for race conditions in data loading

5. Deployment/Infrastructure Failures

Symptoms

• Container won't start
• Health check fails
• Memory/CPU limits exceeded
• Cold start timeouts

Common Causes

Log Patterns

# Azure
"OOMKilled" | "Container terminated"
"Liveness probe failed" | "Readiness probe failed"
"Resource limit exceeded" | "CPU throttled"

Diagnostic Steps

1. Check container logs: az containerapp logs show
2. Check resource metrics in Azure portal
3. Verify health endpoint is fast (< 10s)
4. Check for blocking startup operations

6. Database/External Service Failures

Symptoms

• Slow responses
• "Connection pool exhausted"
• Intermittent 500 errors
• Data inconsistency

Common Causes

Log Patterns

# Backend
"Connection pool exhausted" | "Too many connections"
"Query timeout" | "Lock wait timeout"
"External service error" | "Retry attempt"

Diagnostic Steps

1. Check database metrics (connections, query time)
2. Enable query logging to find slow queries
3. Check external service status pages
4. Add request tracing (LogFire spans)

Correlation Checklist

When multiple services have errors, use this checklist to find root cause:

Time Correlation

• When did errors start? Check deployment history
• Do errors correlate with traffic spikes?
• Are errors periodic (cron jobs, batch processes)?

Service Correlation

• Which service failed first?
• Are downstream services failing due to upstream?
• Is there a shared dependency (database, cache)?

Change Correlation

• What was deployed recently?
• Were environment variables changed?
• Were external services updated?

Pattern Correlation

• Same error across multiple services = shared dependency
• Cascade of 401s = auth service issue
• Timeouts everywhere = network/infrastructure issue

Quick Reference: Error → Action