# Golang Fullstack Error Handling

> Unified Go + GORM + PostgreSQL error handling review. Covers error wrapping, context propagation, PostgreSQL error codes (23505, 40001), errors.Is/As mapping, and retry logic. Ensures proper error chains and robust database failure recovery. Use when this capability is needed.

- Skill: `tomevault-io/golang-fullstack-error-handling` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/golang-fullstack-error-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/golang-fullstack-error-handling/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/golang-fullstack-error-handling

---


# 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

| Priority | Count | Focus |
|---|---|---|
| **CRITICAL** | 6 | error chains, context leaks, PgError mapping, retries |
| **HIGH** | 6 | propagation, Is/As usage, RowsAffected, deadlock detection |
| **MEDIUM** | 2 | sentinel errors, structured logging |

## 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**:
```go
// 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/saifoelloh) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->