Error Wrapping with %w & errors.As

Wrapping adds context to failures while preserving the original cause for inspection.

fmt.Errorf with %w builds an unwrap chain; errors.Is and errors.As traverse that chain so callers recognize sentinels and custom types through intermediate layers.

Summary

Go 1.13 standardized error wrapping: each layer adds operation context (read config, dial db) without destroying the root os.ErrNotExist or your domain type.

errors.As extracts typed data when a sentinel is too coarse.

Use %v when the inner error must not participate in Is/As.

Recipe

Quick-reference recipe card - copy-paste ready.

if err != nil {
    return fmt.Errorf("fetch user %q: %w", id, err)
}
 
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    log.Println("path:", pathErr.Path)
}
 
if errors.Is(err, os.ErrNotExist) {
    return ErrNotFound
}

When to reach for this:

• Every layer between I/O and the handler adds distinct context
• Callers must distinguish timeout vs not-found through wraps
• You need fields from a custom error type mid-chain
• Parallel steps produce multiple errors to aggregate with errors.Join

Working Example

package main
 
import (
	"errors"
	"fmt"
	"net"
	"os"
)
 
type OpError struct {
	Op string
}
 
func (e OpError) Error() string {
	return fmt.Sprintf("%s failed", e.Op)
}
 
func readDB(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		return OpError{Op: "read"}
	}
	return nil
}
 
func loadUser(path string) error {
	if err := readDB(path); err != nil {
		return fmt.Errorf("load user from %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("missing.db")
	var op OpError
	if errors.As(err, &op) {
		fmt.Println("operation:", op.Op)
	}
	fmt.Println("not exist:", errors.Is(err, os.ErrNotExist))
	fmt.Println("net timeout:", errors.Is(err, net.ErrClosed))
}

What this demonstrates:

• Custom type OpError is reachable through a fmt.Errorf wrap
• errors.As requires a pointer to the target type
• errors.Is still finds os.ErrNotExist under OpError if the chain includes it
• Message strings are for humans; Is/As are for program logic

Deep Dive

How It Works

• %w creates a wrapper implementing Unwrap() error.
• errors.Unwrap(err) returns one level; Is/As loop until match or nil.
• Only one %w per fmt.Errorf call is allowed.
• errors.Join(errs...) (Go 1.20+) returns an error that unwraps to multiple values; Is/As check each.

%w vs %v

errors.As Rules

• Second argument must be a pointer to a type that implements error or is a pointer to a struct field.
• Returns true and assigns the first matching value in the chain.
• Prefer value receivers on error types unless you need pointer-specific behavior.

Go Notes

// Typed extraction
var pe *os.PathError
if errors.As(err, &pe) {
    _ = pe.Path
}
 
// Manual one-level unwrap (rare)
inner := errors.Unwrap(err)

Gotchas

• Multiple %w in one Errorf - Compile error. Fix: Wrap once per call; chain with nested fmt.Errorf.
• Passing non-pointer to errors.As - Always fails. Fix: var target MyErr; errors.As(err, &target).
• Pointer vs value receiver on error types - errors.As into *MyErr vs MyErr must match what you return. Fix: Be consistent; document constructor return type.
• Using As for sentinels - errors.Is is simpler for var ErrX. Fix: Reserve As for types with fields.
• Leaking secrets in wrap messages - %w plus verbose logs can expose tokens. Fix: Sanitize messages; use %v at public boundaries.
• Assuming Error() text is stable - Callers must not parse strings. Fix: Export sentinels or types for programmatic checks.

Alternatives

FAQs

Related

• Sentinel Errors & errors.Is - sentinel comparison through chains
• Custom Error Types & Error Interfaces - designing types for As
• Stack Traces with runtime/debug - attach diagnostics to wrapped errors
• Error Handling in Concurrent Code - joining errors from goroutines
• Error Handling Best Practices - wrap policy for teams

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).