Idiomatic Go error handling

Contract

Enforces the Go 1.13 error idioms and Go error-string style on every Go snippet that returns, defines, or inspects an error. Apply whenever you write Go code that can fail: returning an error from a function, declaring error values or types, or branching on which error occurred.

Rules

1. Wrap with %w, never %v / %s / concatenation. When you return an error that came

out of a called function and want to add context, wrap it: fmt.Errorf("<context>: %w", err). The %w verb (Go 1.13) keeps the original error in the chain so callers can still match it with errors.Is / errors.As. %v, %s, and "..." + err.Error() flatten the chain and destroy that.

1. Error strings are lowercase with no trailing punctuation. Every message — the part

before : %w, and every errors.New / Error() string — starts lowercase (unless it begins with a proper noun or an initialism like HTTP, JSON, URL, TLS) and ends with no period, no exclamation mark, no trailing colon. Errors are usually wrapped by callers, so a capitalized / punctuated string reads as send email: Failed to dial.: mid sentence.

1. Context reads operation: %w. Put the added context BEFORE the wrapped error, joined

with a literal ": " (colon then a single space) so the format string ends with : %w: fmt.Errorf("open config %s: %w", path, err). Name the operation that failed; don't restate "error" / "failed to".

1. Sentinel errors: Err-prefixed package vars built with errors.New. A fixed,

comparable error condition is a package-level variable named with the Err prefix (ErrNotFound, ErrTimeout), created with errors.New("...") — not fmt.Errorf, not a struct literal, and not an Error-suffixed or unprefixed name. Unexported sentinels use the lowercase err prefix (errClosed).

1. Error TYPES take the Error SUFFIX and implement Error() string. A custom error

that carries data (fields, codes) is a type named with the Error suffix (ValidationError, RateLimitError) — NOT an Err prefix, which is reserved for sentinel values — with a method of exact signature Error() string (named Error, no arguments, returning string).

1. Match sentinels with errors.Is, never ==. To test whether an error is or wraps a

sentinel, use errors.Is(err, ErrX). err == ErrX only matches an unwrapped error and silently misses a wrapped one.

1. Extract typed errors with errors.As, never a type assertion. To pull out a typed

error and read its fields, declare var target *T and call errors.As(err, &target) — not err.(*T) and not a switch err.(type), both of which miss wrapped errors.

Worked examples

Each pair is BEFORE (the base model's non-idiomatic default) → AFTER (conforming).

Wrap with %w, lowercase, no period.

go
// BEFORE
return fmt.Errorf("Failed to send email: %v", err)
// AFTER
return fmt.Errorf("send email: %w", err)

Sentinel value.

go
// BEFORE
var NotFoundError = fmt.Errorf("Item was not found.")
// AFTER
var ErrNotFound = errors.New("item not found")

Error type carrying data.

go
// BEFORE
type ErrRateLimit struct{ RetryAfter time.Duration }
func (e ErrRateLimit) Msg() string { return "Rate limited." }
// AFTER
type RateLimitError struct{ RetryAfter time.Duration }
func (e *RateLimitError) Error() string {
    return fmt.Sprintf("rate limited, retry after %s", e.RetryAfter)
}

Match a sentinel.

go
// BEFORE
if err == sql.ErrNoRows { return nil, nil }
// AFTER
if errors.Is(err, sql.ErrNoRows) { return nil, nil }

Extract a typed error.

go
// BEFORE
if pe, ok := err.(*os.PathError); ok { log.Print(pe.Path) }
// AFTER
var pe *os.PathError
if errors.As(err, &pe) { log.Print(pe.Path) }

Edge cases & exceptions

• Leading proper noun / initialism stays capitalized: errors.New("EOF while reading"),

fmt.Errorf("JSON decode: %w", err) are fine — the lowercase rule exempts proper nouns and acronyms only.

• Don't wrap when you add no context — returning the bare err is correct; reach for

fmt.Errorf(... %w ...) only when you have real context to add. Never wrap the same error twice.

• One cause per wrap — put a single %w in a given fmt.Errorf; wrap one underlying

error, not several.

• A nil error stays nil — never wrap unconditionally; guard with if err != nil.
• Sentinel vs type: if callers only need to know which error → a sentinel VALUE (Err

prefix, matched with errors.Is). If they need DATA off the error → an error TYPE (Error suffix, matched with errors.As).

Do / Don't

• DON'T wrap with %v or "..." + err.Error(). ALWAYS wrap with %w so the chain survives.
• DON'T capitalize or end an error string with a period. ALWAYS lowercase, no trailing punctuation.
• DON'T name a sentinel NotFoundError / notFound. ALWAYS ErrNotFound, built with errors.New.
• DON'T give an error TYPE the Err prefix. ALWAYS the Error suffix with an Error() string method.
• DON'T compare with err == ErrX. ALWAYS errors.Is(err, ErrX).
• DON'T type-assert err.(*T). ALWAYS errors.As(err, &target).

Common mistakes (the base model's wrong defaults)

• Wrapping with %v (or fmt.Errorf("...", err.Error())), which breaks errors.Is / errors.As downstream.
• Capitalized, period-terminated messages: "Failed to load config.".
• Building a sentinel with fmt.Errorf, or naming it with an Error suffix instead of the Err prefix.
• Giving an error TYPE the Err prefix, or implementing Msg() / String() instead of Error() string.
• Comparing errors with == and type-asserting with .(*T) instead of errors.Is / errors.As.

Quick checklist

• ] Wrapped errors use %w (not %v / %s / concatenation).
• ] Error strings lowercase, no trailing punctuation.
• ] Context is operation: %w (colon + space before %w).
• ] Sentinels: Err-prefixed package vars via errors.New.
• ] Error types: Error suffix + Error() string.
• ] Sentinel checks use errors.Is; typed extraction uses errors.As.