Error Diagnosis

Systematic approach to debugging errors and identifying root causes.

Diagnosis Workflow

1. Reproduce → 2. Isolate → 3. Identify → 4. Fix → 5. Verify

1. Reproduce the Error

• Get exact steps to reproduce
• Note environment (OS, versions, config)
• Check if error is consistent or intermittent
• Capture full error message and stack trace

2. Isolate the Problem

• Identify which component is failing
• Check recent changes (git log, deployments)
• Narrow down to smallest reproducible case
• Check if issue is in your code or dependencies

3. Identify Root Cause

• Read the actual error message carefully
• Follow the stack trace top-to-bottom
• Check logs at the time of failure
• Add temporary logging if needed

4. Fix the Issue

• Address the root cause, not symptoms
• Consider side effects of the fix
• Add tests to prevent regression

5. Verify the Fix

• Reproduce original steps - should work now
• Run full test suite
• Check for unintended side effects

Common Error Patterns

Python Exceptions

Exception	Common Cause	Investigation
KeyError	Missing dict key	Check if key exists before access
AttributeError	None object access	Check for None before method call
TypeError	Wrong argument type	Check function signature and input
ImportError	Missing/circular import	Check import paths and dependencies
ConnectionError	Network/DB issues	Check connectivity and credentials

Stack Trace Analysis

# Example stack trace:
# Traceback (most recent call last):
#   File "app.py", line 42, in handle_request    ← Entry point
#     result = process_data(data)
#   File "processor.py", line 15, in process_data ← Intermediate
#     return transform(data['key'])
#   File "processor.py", line 8, in transform      ← Root cause
#     return value.upper()
# AttributeError: 'NoneType' object has no attribute 'upper'

# The error is at line 8, but the fix might be:
# - Line 15: Check if 'key' exists in data
# - Line 8: Check if value is None before .upper()
# - Caller: Ensure data is properly validated

Database Errors

Error	Likely Cause	Fix
Connection refused	DB not running	Start DB, check port
Authentication failed	Bad credentials	Check env vars
Timeout	Long query or lock	Optimize query, check locks
Unique constraint	Duplicate data	Handle conflict or validate first
Foreign key violation	Invalid reference	Check referential integrity

API Errors

Status	Meaning	Investigation
400	Bad request	Check request body/params
401	Unauthorized	Check auth token
403	Forbidden	Check permissions
404	Not found	Check URL path
500	Server error	Check server logs
502/503	Service unavailable	Check upstream services

Debugging Commands

Python

# Quick debugging
import pdb; pdb.set_trace()  # Breakpoint

# Better: ipdb or pudb
import ipdb; ipdb.set_trace()

# Inspect object
print(vars(obj))
print(dir(obj))

# Pretty print
from pprint import pprint
pprint(complex_dict)

# Get traceback
import traceback
traceback.print_exc()

Logging Investigation

# Search logs for errors
grep -i "error\|exception\|traceback" app.log

# Get context around error
grep -B 5 -A 10 "ERROR" app.log

# Follow logs in real-time
tail -f app.log | grep --line-buffered "ERROR"

# Count error types
grep "ERROR" app.log | cut -d':' -f4 | sort | uniq -c | sort -rn

Git Investigation

# What changed recently?
git log --oneline -20

# What changed in specific file?
git log --oneline -p -- path/to/file.py

# Who changed this line?
git blame path/to/file.py -L 42,42

# Find when bug was introduced
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
# Test at each step until found

Database Investigation

-- Check for locks (PostgreSQL)
SELECT * FROM pg_locks WHERE granted = false;

-- Active queries
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;

-- Kill stuck query
SELECT pg_cancel_backend(pid);

Error Report Template

## Error Report

### Summary
{One-line description of the error}

### Environment
- OS: {os}
- Version: {app version}
- Config: {relevant config}

### Steps to Reproduce
1. {Step 1}
2. {Step 2}
3. {Step 3}

### Expected Behavior
{What should happen}

### Actual Behavior
{What actually happens}

### Error Message

{Full error message and stack trace}

### Logs

{Relevant log entries}

### Root Cause Analysis
{What is causing this error}

### Proposed Fix
{How to fix it}

### Impact
- Severity: Critical/High/Medium/Low
- Affected users: {scope}
- Workaround: {if any}

Debugging Mindset

1. Read the error message - It usually tells you what's wrong
2. Check the obvious first - Typos, missing config, wrong version
3. Reproduce before fixing - Don't guess at the problem
4. One change at a time - Isolate what fixes it
5. Document the fix - Help future you and others