Sentinel Errors & errors.Is

Sentinel errors are package-level variables that represent a fixed failure identity.

Callers recognize them with errors.Is instead of string matching or brittle == checks that break once errors are wrapped.

Summary

Sentinel errors give your API a small vocabulary of stable outcomes: not found, already exists, canceled, invalid input.

Go 1.13 added errors.Is so those identities survive fmt.Errorf("...: %w", err) wrap chains.

Use sentinels for cross-package contracts; reach for custom types when callers need structured fields.

Recipe

Quick-reference recipe card - copy-paste ready.

var ErrNotFound = errors.New("not found")
 
func Find(id string) (Item, error) {
    if id == "" {
        return Item{}, ErrNotFound
    }
    return Item{}, nil
}
 
if errors.Is(err, ErrNotFound) {
    // handle missing resource
}

When to reach for this:

• A failure mode is part of your public API contract
• Callers need a boolean branch without parsing strings
• The error has no extra fields beyond its identity
• Standard library patterns (io.EOF, os.ErrNotExist) apply to your domain

Working Example

package main
 
import (
	"errors"
	"fmt"
	"os"
)
 
var ErrUserNotFound = errors.New("user not found")
 
func loadUser(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		if os.IsNotExist(err) {
			return fmt.Errorf("load user %q: %w", path, ErrUserNotFound)
		}
		return fmt.Errorf("load user %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("alice.json")
	switch {
	case errors.Is(err, ErrUserNotFound):
		fmt.Println("client: 404 user missing")
	case err != nil:
		fmt.Println("client: 500", err)
	default:
		fmt.Println("ok")
	}
}

What this demonstrates:

• A domain sentinel (ErrUserNotFound) maps to a client outcome
• fmt.Errorf with %w preserves both os and domain sentinels in the chain
• errors.Is finds ErrUserNotFound through wraps
• os.IsNotExist is a convenience wrapper around errors.Is(err, os.ErrNotExist)

Deep Dive

How It Works

• errors.New returns an opaque error value with a fixed identity.
• Wrapping with %w implements Unwrap() error, linking outer and inner errors.
• errors.Is(err, target) returns true if err == target or any unwrap step matches.
• Direct err == ErrX fails when a wrapper sits between caller and sentinel.

Sentinel Naming and Placement

io.EOF and Control Flow

io.EOF signals end of stream during Read, not necessarily a catastrophic failure.

Loop until errors.Is(err, io.EOF) after processing the final chunk.

Go Notes

// Bad: breaks after wrap
if err == ErrNotFound { ... }
 
// Good
if errors.Is(err, ErrNotFound) { ... }
 
// Also good for stdlib helpers
if os.IsNotExist(err) { ... }

Gotchas

• Using == after wrapping - Wrapped errors never equal the sentinel. Fix: Use errors.Is.
• Too many sentinels - Dozens of ErrX variables become hard to document. Fix: Group related failures into a typed error or error code enum.
• Exporting internal sentinels - Callers depend on values you cannot evolve. Fix: Export only stable contract errors; keep helpers unexported.
• String matching with strings.Contains - Fragile across wraps and wording changes. Fix: errors.Is or errors.As.
• Returning typed nil pointers - return (*MyError)(nil) makes err != nil true. Fix: return nil or var err error = nil.
• Treating every EOF as failure - Read loops expect EOF. Fix: Branch on errors.Is(err, io.EOF) separately from real errors.

Alternatives

FAQs

Related

• Errors as Values: Go's Error Philosophy - why explicit errors exist
• Error Wrapping with %w & errors.As - chains and typed inspection
• Custom Error Types & Error Interfaces - when sentinels are not enough
• API Error Design for HTTP and gRPC Services - mapping to status codes
• Error Handling Best Practices - team conventions

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