z-go-errors

Go errors

Core rules

1. Check every error — never discard with _.
2. Wrap with context: fmt.Errorf("create user: %w", err) — short prefix, lowercase, no period.
3. Translate errors at transport boundaries — %v removes wrapping but does not sanitize the message. Return stable public errors; retain internal causes for one safe log.
4. Inspect via `errors.Is` / `errors.As` — never == on wrapped errors or bare type assertions.
5. Handle exactly once — log OR return, never both (see Single Handling below).
6. Panic only for truly unrecoverable states — programmer errors, broken invariants; never for expected conditions.

Wrapping and inspection

// wrap
return fmt.Errorf("fetch user %s: %w", id, err)

// sentinel check — works through the chain
if errors.Is(err, ErrNotFound) { ... }

// typed check
var ve *ValidationError
if errors.As(err, &ve) { ... }

// combine independent errors (Go 1.20+)
return errors.Join(errA, errB)

Sentinel vs custom type

// sentinel — unexported, exported error value
var ErrNotFound = errors.New("not found")

// custom type — carries data
type ValidationError struct {
    Field   string
    Message string
}
func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation %s: %s", e.Field, e.Message)
}

Error var names: ErrFoo. Error type names: FooError. Error strings: lowercase, no trailing punctuation.

Single handling rule

An error must be logged OR returned, never both. Violating this creates duplicate log lines and buries the wrapped chain during incidents.

Interior code (repos, services, domain): wrap and return only.

// before — log-and-return violation
if err != nil {
    logger.Error("query failed", "err", err)
    return fmt.Errorf("query: %w", err)
}

// after
if err != nil {
    return fmt.Errorf("query: %w", err)
}

Boundary code (HTTP handler, gRPC interceptor, worker loop, main): log and absorb. Never log inside interior layers; the boundary does it once.

// boundary: worker loop
for job := range w.jobs {
    if err := w.process(ctx, job); err != nil {
        w.logger.Error("job failed", "job_id", job.ID, "err", err)
        // handle: retry, mark failed, etc.
    }
}

False positives — do NOT fix

Panic discipline

// Only for programmer errors / broken invariants
func mustPositive(n int) int {
    if n <= 0 {
        panic(fmt.Sprintf("mustPositive: got %d", n))
    }
    return n
}

Do not recover an unexpected panic merely to keep a server or worker alive. A broken invariant can leave shared state unsafe even when the goroutine exits.

If an existing package uses an internal panic protocol, recover only its private panic type at the package boundary and re-panic every unexpected value. Define the returned error and resource cleanup. Any broader containment boundary must establish state isolation, define the failed operation's result, and preserve stack diagnostics; a goroutine boundary alone provides no such guarantee.

Quick reference

Do not

• Log AND return in the same error branch (interior code).
• Use == to compare errors that may be wrapped.
• Use bare type assertions on errors — use errors.As.
• Produce high-cardinality data in the stable log message; attach as structured attrs.
• Expose raw internal errors to external callers — translate at the boundary.
• Convert every panic to an error or log entry without a containment contract.

Verify

go build ./... && timeout 5m go test -parallel 4 -p 2 -short -timeout 2m ./...
golangci-lint run ./...

Review any recovery path for its accepted panic values, unexpected-value propagation, cleanup, and explicit failure result.

Sources

• Google Go best practices: program checks and panics, controlled panic recovery.