Error Handling

Explicit error values and wrapping. Results appear in the same fence: same-line // comments when short, multiline // blocks below the sample when not.

errors.New

Simple sentinel or message errors.

err := errors.New("boom")
err.Error()  // "boom"

fmt.Errorf wrap

Wrap with %w for errors.Is/As.

base := errors.New("root")
err := fmt.Errorf("load: %w", base)
errors.Is(err, base)  // true

errors.Is

Check sentinel in a chain.

var ErrNotFound = errors.New("not found")
err := fmt.Errorf("user: %w", ErrNotFound)
errors.Is(err, ErrNotFound)  // true

errors.As

Extract typed error from chain.

type MyErr struct{ Code int }
func (e *MyErr) Error() string { return "my" }
err := fmt.Errorf("x: %w", &MyErr{Code: 7})
var me *MyErr
errors.As(err, &me)  // true
// me.Code == 7

panic recover

Recover only in defer; convert to error at boundaries.

func safe() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic: %v", r)
        }
    }()
    panic("x")
}
// safe() returns error

Multiple Errors

Join with errors.Join (Go 1.20+).

err := errors.Join(errors.New("a"), errors.New("b"))
err != nil  // true

Custom Error Type

Struct implementing Error().

type E struct{ Msg string }
func (e E) Error() string { return e.Msg }
E{Msg: "nope"}.Error()  // "nope"

Early Return

Idiomatic if err != nil { return }.

// v, err := f()
// if err != nil { return err }
// use v

Unwrap

Manual unwrap if needed.

base := errors.New("b")
err := fmt.Errorf("a: %w", base)
errors.Unwrap(err) == base  // true

Ignore Error Rare

_ = only when intentionally discarding.

_ = os.Remove("tmp")  // best-effort cleanup

fmt %v vs %w

%v stringifies; %w wraps.

e := errors.New("x")
fmt.Errorf("%v", e).Error()  // "x" (not wrap)

os.ErrNotExist

Standard library sentinels.

errors.Is(fs.ErrNotExist, fs.ErrNotExist)  // true

context.Canceled

Check context errors.

errors.Is(context.Canceled, context.Canceled)  // true

Must Helpers

Panic on error in init/tests - not request path.

// func must[T any](v T, err error) T { if err != nil { panic(err) }; return v }

Error String Stable

Keep Error() messages stable for logs, not for branching - use Is/As.

// branch on errors.Is, not strings.Contains(err.Error())

Functions and Methods - (T, error) returns
Interfaces and Generics - error interface
Testing and Tooling - assert errors

Effective Go - Official guide to writing clear, idiomatic Go.
Go Standard Library Documentation - Complete reference for the standard library.
Go by Example - Annotated practical code examples.
Learning Go (2nd Edition) - Jon Bodner.
The Go Programming Language (Paperback) - Donovan & Kernighan paperback.

Stack versions: Go 1.26.x · chi/gin/echo latest (verify at build)

Reviewed by Chris St. John·Last updated Jul 18, 2026

Was this article helpful?

Reference Code Reference Error Go

Error Handling

Explicit error values and wrapping. Results appear in the same fence: same-line // comments when short, multiline // blocks below the sample when not.

errors.New

Simple sentinel or message errors.

err := errors.New("boom")
err.Error()  // "boom"

fmt.Errorf wrap

Wrap with %w for errors.Is/As.

base := errors.New("root")
err := fmt.Errorf("load: %w", base)
errors.Is(err, base)  // true

errors.Is

Check sentinel in a chain.

var ErrNotFound = errors.New("not found")
err := fmt.Errorf("user: %w", ErrNotFound)
errors.Is(err, ErrNotFound)  // true

errors.As

Extract typed error from chain.

type MyErr struct{ Code int }
func (e *MyErr) Error() string { return "my" }
err := fmt.Errorf("x: %w", &MyErr{Code: 7})
var me *MyErr
errors.As(err, &me)  // true
// me.Code == 7

panic recover

Recover only in defer; convert to error at boundaries.

func safe() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic: %v", r)
        }
    }()
    panic("x")
}
// safe() returns error

Multiple Errors

Join with errors.Join (Go 1.20+).

err := errors.Join(errors.New("a"), errors.New("b"))
err != nil  // true

Custom Error Type

Struct implementing Error().

type E struct{ Msg string }
func (e E) Error() string { return e.Msg }
E{Msg: "nope"}.Error()  // "nope"

Early Return

Idiomatic if err != nil { return }.

// v, err := f()
// if err != nil { return err }
// use v

Unwrap

Manual unwrap if needed.

base := errors.New("b")
err := fmt.Errorf("a: %w", base)
errors.Unwrap(err) == base  // true

Ignore Error Rare

_ = only when intentionally discarding.

_ = os.Remove("tmp")  // best-effort cleanup

fmt %v vs %w

%v stringifies; %w wraps.

e := errors.New("x")
fmt.Errorf("%v", e).Error()  // "x" (not wrap)

os.ErrNotExist

Standard library sentinels.

errors.Is(fs.ErrNotExist, fs.ErrNotExist)  // true

context.Canceled

Check context errors.

errors.Is(context.Canceled, context.Canceled)  // true

Must Helpers

Panic on error in init/tests - not request path.

// func must[T any](v T, err error) T { if err != nil { panic(err) }; return v }

Error String Stable

Keep Error() messages stable for logs, not for branching - use Is/As.

// branch on errors.Is, not strings.Contains(err.Error())

Functions and Methods - (T, error) returns
Interfaces and Generics - error interface
Testing and Tooling - assert errors

Effective Go - Official guide to writing clear, idiomatic Go.
Go Standard Library Documentation - Complete reference for the standard library.
Go by Example - Annotated practical code examples.
Learning Go (2nd Edition) - Jon Bodner.
The Go Programming Language (Paperback) - Donovan & Kernighan paperback.

Stack versions: Go 1.26.x · chi/gin/echo latest (verify at build)

Reviewed by Chris St. John·Last updated Jul 18, 2026

Was this article helpful?

Error Handling

Search Documentation

Error Handling