golang-error-handling

Files (4)

• SKILL.md
• error-creation.md · references/
• error-handling.md · references/
• error-wrapping.md · references/

SKILL.md (first lines)

# Go Error Handling

Treat errors as part of the API. Preserve enough identity and context for the owner to act, without leaking secrets or coupling callers to accidental implementation details.

## Inspect the existing contract

Before editing:

1. Read repository conventions, public documentation, tests, and callers using `errors.Is` or `errors.As`.
2. Identify the layer that can decide retry, fallback, user response, process exit, or logging.
3. Separate expected domain outcomes from infrastructure failures and programmer defects.
4. Preserve stable sentinels, types, status mappings, and wire responses unless changing the contract is requested.

## Propagate useful information

Check errors unless the API documents that they are ignorable and the code explains why. Add wrapping context when it identifies the failed operation or boundary:

```go
value, err := store.Load(ctx, id)
if err != nil {
    return Item{}, fmt.Errorf("loading item %q: %w", id, err)
}
```

Do not wrap at every stack frame mechanically; repeated “failed to” prefixes add noise. Use `%w` only when exposing the wrapped error's identity is part of the intended contract. At a public or trust boundary, translate to a stable domain or transport error instead of assuming `%v` makes the message safe—it breaks unwrapping but still includes the original text.

Use `errors.Is` for semantic matching through a chain and `errors.As` for typed detail. Avoid direct equality or type assertions when wrapping is allowed. See [wrapping and inspection](references/error-wrapping.md).

## Choose an error representation

- Use a package sentinel when callers need to recognize one stable condition and no extra fields are needed.
- Use a custom type when callers need structured detail. Keep its `Error` text safe for likely logs and implement `Unwrap` when the cause is intentionally exposed.
- Use an ordinary wrapped error for one-off operational context that callers do not classify more precisely.
- Use `errors.Join` when the project's Go version supports it, failures are independent, callers can meaningfully inspect a multi-error, and deterministic ordering is preserved where needed.

Read [creating error contracts](references/error-creation.md) for API decisions.

## Handle at an ownership boundary

Normally, lower layers annotate and return; a boundary that owns the outcome logs, maps, retries, or terminates. Logging and returning the same incident from several layers creates duplicate events. A lower layer may log and return when it records a distinct operational event, but the reason and deduplication behavior should be clear.

Keep log messages stable and put IDs, paths, counts, and the error in structured attributes. Redact credentials, tokens, personal data, query contents, and sensitive paths according to project policy. Do not return internal error text directly to untrusted users.

For boundary logging and panic decisions, read [handling and recovery](references/error-handling.md).

## Verification

Test observable behavior rather than exact incidental strings:

- `errors.Is` and `errors.As` contracts survive wrapping;
- domain and transport mappings remain correct;
- multi-errors retain all required causes;
- cancellation and deadline errors are not misclassified as internal failures;
- sensitive details do not cross public boundaries;
- cleanup errors are not lost.

When reviewing, state the caller action that fails because of the current error design. Style-only rewrites of already useful errors are low value.

From reagin/agent-skills, MIT.

More from reagin/agent-skills