gh-iciakky-cc-general-skills/skills/debug/references/common_patterns.md

Common Bug Patterns and Signatures

This reference documents frequently encountered bug patterns, their signatures, and diagnostic approaches.

Pattern Categories

1. Timing and Concurrency Issues

Race Conditions

Signature:

• Intermittent failures
• Works in development but fails in production
• Different results with same input
• Failures during high load

Common Causes:

• Shared mutable state without synchronization
• Incorrect thread-safety assumptions
• Async operations completing in unexpected order

Investigation Approach:

• Add extensive logging with timestamps
• Use debugger breakpoints sparingly (changes timing)
• Add delays to expose race windows
• Review all shared state access patterns

Deadlocks

Signature:

• Application hangs indefinitely
• No error messages
• High CPU or complete freeze
• Multiple threads waiting

Common Causes:

• Circular wait for locks
• Lock ordering violations
• Database transaction deadlocks

Investigation Approach:

• Check thread dumps / stack traces
• Review lock acquisition order
• Use database deadlock detection tools
• Add timeout mechanisms

2. Memory Issues

Memory Leaks

Signature:

• Gradually increasing memory usage
• Performance degradation over time
• Out of memory errors after extended runtime
• Works initially, fails after hours/days

Common Causes:

• Event listeners not cleaned up
• Cache without eviction policy
• Circular references preventing garbage collection
• Resource handles not closed

Investigation Approach:

• Profile memory over time
• Take heap dumps at intervals
• Compare object counts between snapshots
• Check for unclosed resources (files, connections, sockets)

Stack Overflow

Signature:

• Stack overflow error
• Deep recursion errors
• Crashes at predictable depth

Common Causes:

• Unbounded recursion
• Missing base case in recursive function
• Circular data structure traversal

Investigation Approach:

• Check recursion depth
• Verify base case conditions
• Look for circular references
• Consider iterative alternative

3. State Management Issues

Stale Cache

Signature:

• Outdated data displayed
• Inconsistency between systems
• Works after cache clear
• Different results on different servers

Common Causes:

• Cache invalidation not triggered
• TTL too long
• Distributed cache synchronization issues

Investigation Approach:

• Check cache invalidation logic
• Verify cache key generation
• Test with cache disabled
• Review cache update patterns

State Corruption

Signature:

• Invalid state transitions
• Data inconsistency
• Unexpected null values
• Objects in impossible states

Common Causes:

• Direct state mutation
• Missing validation
• Incorrect error handling leaving partial updates
• Concurrent modifications

Investigation Approach:

• Add state validation assertions
• Review state mutation points
• Check transaction boundaries
• Look for error handling gaps

4. Integration Issues

API Failures

Signature:

• Timeout errors
• 500/503 errors
• Network errors
• Rate limiting responses

Common Causes:

• Third-party API downtime
• Network connectivity issues
• Authentication token expiration
• Rate limits exceeded

Investigation Approach:

• Check API status pages
• Verify network connectivity
• Review authentication flow
• Check rate limit headers
• Test with API directly (curl/Postman)

Database Issues

Signature:

• Connection pool exhausted
• Slow query performance
• Lock wait timeouts
• Connection refused errors

Common Causes:

• Connection leaks (not closing connections)
• Missing indexes causing full table scans
• N+1 query problems
• Database server overload

Investigation Approach:

• Monitor connection pool metrics
• Review slow query logs
• Check execution plans
• Look for repeated queries in loops

5. Configuration Issues

Environment Mismatches

Signature:

• Works locally, fails in production
• Different behavior across environments
• "It works on my machine"

Common Causes:

• Different environment variables
• Different dependency versions
• Different configuration files
• Platform-specific code paths

Investigation Approach:

• Compare environment variables
• Check dependency versions (package-lock.json, poetry.lock, etc.)
• Review configuration for environment-specific values
• Check platform-specific code paths

Missing Dependencies

Signature:

• Module not found errors
• Import errors
• Class/function not defined
• Version incompatibility errors

Common Causes:

• Missing package in requirements
• Outdated dependency versions
• Peer dependency conflicts
• System library missing

Investigation Approach:

• Review dependency manifests
• Check installed versions vs required
• Look for dependency conflicts
• Verify system libraries installed

6. Logic Errors

Off-by-One Errors

Signature:

• Index out of bounds
• Missing first or last element
• Infinite loops
• Incorrect boundary handling

Common Causes:

• Using < instead of <=
• 0-indexed vs 1-indexed confusion
• Incorrect loop conditions

Investigation Approach:

• Check boundary conditions
• Test with edge cases (empty, single element)
• Review loop conditions carefully
• Add assertions for expected ranges

Type Coercion Bugs

Signature:

• Unexpected type errors
• Comparison behaving unexpectedly
• String concatenation instead of addition
• Falsy value handling issues

Common Causes:

• Implicit type conversion
• Loose equality checks (== vs ===)
• Type assumptions without validation
• Mixed numeric types

Investigation Approach:

• Add explicit type checks
• Use strict equality
• Add type annotations/hints
• Check for implicit conversions

7. Error Handling Issues

Swallowed Exceptions

Signature:

• Silent failures
• No error messages despite failure
• Incomplete operations
• Success reported despite failure

Common Causes:

• Empty catch blocks
• Broad exception catching
• Returning default values on error
• Not re-raising exceptions

Investigation Approach:

• Search for empty catch/except blocks
• Review exception handling patterns
• Add logging to all error paths
• Check for bare except/catch clauses

Error Propagation Failures

Signature:

• Low-level errors exposed to users
• Unclear error messages
• Generic "Something went wrong"
• Stack traces in user interface

Common Causes:

• No error translation layer
• Missing error boundaries
• Not catching specific exceptions
• No user-friendly error messages

Investigation Approach:

• Review error handling architecture
• Check error message clarity
• Verify error boundaries exist
• Test error scenarios

Pattern Recognition Strategies

Look for These Red Flags:

1. Time-based behavior: If adding delays changes behavior, suspect timing issues
2. Load-based failures: If failures increase with load, suspect resource exhaustion or race conditions
3. Environment-specific: If only fails in certain environments, suspect configuration differences
4. Gradual degradation: If performance worsens over time, suspect memory leaks or resource leaks
5. Intermittent failures: If behavior is non-deterministic, suspect concurrency issues or external dependencies

Diagnostic Quick Checks:

1. Can you reproduce it consistently? No → Likely timing/concurrency issue
2. Does it fail immediately? Yes → Likely configuration or initialization issue
3. Does it fail after some time? Yes → Likely resource leak or state corruption
4. Does it fail with specific input? Yes → Likely validation or edge case handling issue
5. Does it fail only in production? Yes → Likely environment or load-related issue

Using This Reference

When encountering a bug:

1. Match the signature to patterns above
2. Review common causes for that pattern
3. Follow the investigation approach
4. Apply lessons from similar past issues
5. Update this document if you discover new patterns