Error Handling Best Practices

Consistent error strategy across libraries vs applications.

Go teams ship faster when every package agrees on how errors are created, wrapped, inspected, logged, and exposed to clients.

These rules turn the error-handling articles in this section into reviewable habits for libraries, services, and CLIs.

How to Use This List

Apply during API design, handler implementation, and code review for any function returning error.
Libraries and applications have different jobs: return vs translate.
Revisit when onboarding or when a service adds gRPC alongside HTTP.

A - Core Discipline

Check every error return immediately. Ignored errors are bugs; use linters (errcheck) in CI.
Return (zero, err) on failure; never use the success value when err != nil. Callers depend on this invariant.
Use errors.Is and errors.As instead of == and string matching. Survives wrap chains and wording changes.
Wrap with fmt.Errorf("operation: %w", err) to add context. One wrap per layer with meaningful operation names.
Return nil error on success, not typed nil pointers. Prevents err != nil surprises on success paths.

B - Library vs Application

Libraries return errors; they do not log and return the same error. Avoid duplicate log noise unless adding unique context unavailable upstream.
Applications map errors to HTTP/gRPC status at handlers or interceptors. Domain packages stay transport-agnostic.
Export only stable sentinel and type contracts. Unexported errors free you to refactor internals.
Do not panic for expected validation or I/O failures in libraries. Return error so callers control exit behavior.
Use %v instead of %w at public boundaries when inner causes must stay hidden. Security and abstraction trade-off.

C - API and Client Contracts

Expose stable machine-readable codes (problem type, gRPC code), not raw Error() text. Clients branch on codes.
Map context.DeadlineExceeded to timeout responses (504/408, gRPC deadline exceeded). Distinguish timeouts from not-found.
Log 5xx causes with request ID; return opaque messages to clients. Include stacks only server-side.
Document which errors are retryable. Optional Retryable() bool or documented gRPC code policy.
Keep validation errors aggregated with errors.Join when all fields matter. Single response listing every failure.

D - Concurrency and Operations

Never write shared err variables from goroutines without synchronization. Use channels or errgroup.
Cancel sibling work on first failure with errgroup.WithContext. Saves quotas and CPU.
Propagate context.Context and wrap ctx.Err() with %w. Callers distinguish cancel vs I/O failure.
Capture debug.Stack in application diagnostics, not in reusable libraries. Stacks are for operators.
Test error paths: errors.Is, errors.As, and mapped HTTP/gRPC status. Success-path-only tests miss regressions.

E - Style and Maintenance

Name sentinels ErrX in PascalCase. Matches standard library conventions.
Prefer few sentinels; use custom types when fields are required. Avoid exception-style hierarchies.
Keep Error() strings concise and stable in meaning. Program logic uses fields and Is/As, not substrings.
Review new external dependencies for error wrapping behavior. ORMs and SDKs may need adapter mappers.
Align team ADR on 400 vs 422 for validation and stick to it. Mixed policies break client SDKs.

FAQs

Should every layer log errors?

No. Log at boundaries or when adding unique diagnostic context. Otherwise return wrapped errors upstream.

When is wrapping unnecessary?

When the error already contains sufficient context for the next caller, or when using %v to intentionally hide the chain.

How many exported errors should a package have?

As few as possible for the documented contract. Prefer extending codes on a type over adding many sentinels.

Should CLI main functions exit with codes?

Yes. Map errors.Is outcomes to exit 1/2/etc. and print user-friendly messages to stderr.

Are string comparisons ever acceptable?

Rarely for user-facing CLI output. Never for library logic; use Is/As.

How do best practices differ for internal monorepos?

Shared domain packages stay transport-agnostic; each binary (API, worker, CLI) owns mapping and logging policy.

Should I use github.com/pkg/errors?

Prefer stdlib %w, errors.Is, and errors.As in new code. Legacy stacks may wrap gradually.

What linter rules help?

Enable errcheck, errorlint, and wrapcheck (team policy) in golangci-lint for consistent wrap and compare style.

How do I document errors for API consumers?

OpenAPI/gRPC docs listing stable codes and statuses; never document internal driver strings.

When should errors.Join replace errgroup?

When you need all failures collected, not fail-fast. Validation and batch linting are common cases.

Should tests assert exact error strings?

Assert errors.Is/As and fields. String equality breaks when messages gain context wraps.

How often should teams revisit error ADRs?

When adding transports (gRPC, GraphQL), changing auth, or after incidents caused by ambiguous status mapping.

Errors as Values: Go's Error Philosophy - conceptual foundation
Error Handling Basics - runnable section intro
Sentinel Errors & errors.Is - sentinel rules in depth
Error Wrapping with %w & errors.As - wrap mechanics
API Error Design for HTTP and gRPC Services - client contracts

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

Error Handling Best Practices

Consistent error strategy across libraries vs applications.

Go teams ship faster when every package agrees on how errors are created, wrapped, inspected, logged, and exposed to clients.

These rules turn the error-handling articles in this section into reviewable habits for libraries, services, and CLIs.

How to Use This List

Apply during API design, handler implementation, and code review for any function returning error.
Libraries and applications have different jobs: return vs translate.
Revisit when onboarding or when a service adds gRPC alongside HTTP.

A - Core Discipline

Check every error return immediately. Ignored errors are bugs; use linters (errcheck) in CI.
Return (zero, err) on failure; never use the success value when err != nil. Callers depend on this invariant.
Use errors.Is and errors.As instead of == and string matching. Survives wrap chains and wording changes.
Wrap with fmt.Errorf("operation: %w", err) to add context. One wrap per layer with meaningful operation names.
Return nil error on success, not typed nil pointers. Prevents err != nil surprises on success paths.

B - Library vs Application

Libraries return errors; they do not log and return the same error. Avoid duplicate log noise unless adding unique context unavailable upstream.
Applications map errors to HTTP/gRPC status at handlers or interceptors. Domain packages stay transport-agnostic.
Export only stable sentinel and type contracts. Unexported errors free you to refactor internals.
Do not panic for expected validation or I/O failures in libraries. Return error so callers control exit behavior.
Use %v instead of %w at public boundaries when inner causes must stay hidden. Security and abstraction trade-off.

C - API and Client Contracts

Expose stable machine-readable codes (problem type, gRPC code), not raw Error() text. Clients branch on codes.
Map context.DeadlineExceeded to timeout responses (504/408, gRPC deadline exceeded). Distinguish timeouts from not-found.
Log 5xx causes with request ID; return opaque messages to clients. Include stacks only server-side.
Document which errors are retryable. Optional Retryable() bool or documented gRPC code policy.
Keep validation errors aggregated with errors.Join when all fields matter. Single response listing every failure.

D - Concurrency and Operations

Never write shared err variables from goroutines without synchronization. Use channels or errgroup.
Cancel sibling work on first failure with errgroup.WithContext. Saves quotas and CPU.
Propagate context.Context and wrap ctx.Err() with %w. Callers distinguish cancel vs I/O failure.
Capture debug.Stack in application diagnostics, not in reusable libraries. Stacks are for operators.
Test error paths: errors.Is, errors.As, and mapped HTTP/gRPC status. Success-path-only tests miss regressions.

E - Style and Maintenance

Name sentinels ErrX in PascalCase. Matches standard library conventions.
Prefer few sentinels; use custom types when fields are required. Avoid exception-style hierarchies.
Keep Error() strings concise and stable in meaning. Program logic uses fields and Is/As, not substrings.
Review new external dependencies for error wrapping behavior. ORMs and SDKs may need adapter mappers.
Align team ADR on 400 vs 422 for validation and stick to it. Mixed policies break client SDKs.

FAQs

Should every layer log errors?

No. Log at boundaries or when adding unique diagnostic context. Otherwise return wrapped errors upstream.

When is wrapping unnecessary?

When the error already contains sufficient context for the next caller, or when using %v to intentionally hide the chain.

How many exported errors should a package have?

As few as possible for the documented contract. Prefer extending codes on a type over adding many sentinels.

Should CLI main functions exit with codes?

Yes. Map errors.Is outcomes to exit 1/2/etc. and print user-friendly messages to stderr.

Are string comparisons ever acceptable?

Rarely for user-facing CLI output. Never for library logic; use Is/As.

How do best practices differ for internal monorepos?

Shared domain packages stay transport-agnostic; each binary (API, worker, CLI) owns mapping and logging policy.

Should I use github.com/pkg/errors?

Prefer stdlib %w, errors.Is, and errors.As in new code. Legacy stacks may wrap gradually.

What linter rules help?

Enable errcheck, errorlint, and wrapcheck (team policy) in golangci-lint for consistent wrap and compare style.

How do I document errors for API consumers?

OpenAPI/gRPC docs listing stable codes and statuses; never document internal driver strings.

When should errors.Join replace errgroup?

When you need all failures collected, not fail-fast. Validation and batch linting are common cases.

Should tests assert exact error strings?

Assert errors.Is/As and fields. String equality breaks when messages gain context wraps.

How often should teams revisit error ADRs?

When adding transports (gRPC, GraphQL), changing auth, or after incidents caused by ambiguous status mapping.

Errors as Values: Go's Error Philosophy - conceptual foundation
Error Handling Basics - runnable section intro
Sentinel Errors & errors.Is - sentinel rules in depth
Error Wrapping with %w & errors.As - wrap mechanics
API Error Design for HTTP and gRPC Services - client contracts

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).

Error Handling Best Practices

Search Documentation

Error Handling Best Practices