Error Handling (Unified Go & DB)

Expert-level review for error handling in Go services using GORM and PostgreSQL. Ensures errors are correctly identified, preserved via wrapping, mapped to domain errors, and retried where appropriate.

When to Apply

Use this skill when:

• Reviewing general Go error propagation and context usage
• Debugging database errors (e.g., duplicate keys, serialization failures)
• Auditing error wrapping with %w vs %v
• Ensuring correct use of errors.Is / errors.As
• Adding retry logic for serializable transactions or deadlocks

Rule Categories

Rules Covered (14 total)

Critical Issues (6)

• critical-error-wrapping — Use %w, not %v, to preserve error chains
• critical-context-leak — Always defer cancel() after context creation
• critical-error-shadow — Don't shadow err in nested scopes
• critical-errors-is-as — Use errors.Is/As for DB and wrapped errors
• critical-pg-error-mapping — Map Postgres codes to domain errors at repo boundary
• critical-serialization-retry — Retry transactions on 40001 serialization failure

High-Impact Patterns (6)

• high-context-propagation — Propagate context through the call chain
• high-error-is-as — Prescriptive rule for using Is/As over string matching
• high-interface-nil — Check for nil in interfaces correctly
• high-rows-affected — Check RowsAffected after Update/Delete
• high-wrap-with-context — Wrap DB errors with operation context
• high-deadlock-detection — Handle 40P01 deadlocks as retryable

Medium Improvements (2)

• medium-sentinel-error-usage — Use sentinel errors for stable categories
• medium-structured-logging — Log DB/Go errors with structured fields

Trigger Phrases

• "Review error handling"
• "Debug this DB error"
• "23505 / 40001 / 40P01"
• "Check for context leaks"
• "Review error chains"
• "Transaction retry"
• "ErrRecordNotFound"

Output Format

## Critical Issues Found: X

### [Rule ID] (Line Y)
**Issue**: Description
**Impact**: Context leak / Lost chain / Data inconsistency
**Fix**: Suggested code
**Example**:

// Corrected code

Related Skills

• [gorm-query-patterns](../gorm-query-patterns/SKILL.md) — For .Error check safety
• [concurrency-safety](../concurrency-safety/SKILL.md) — For context timeout patterns