go-error-handling

Go Error Handling

Comprehensive error handling patterns for production Go code.

Return Errors, Do Not Panic

Production code must avoid panics. Return errors and let callers decide how to handle them.

// Wrong
func run(args []string) {
    if len(args) == 0 {
        panic("an argument is required")
    }
}

// Correct
func run(args []string) error {
    if len(args) == 0 {
        return errors.New("an argument is required")
    }
    return nil
}

func main() {
    if err := run(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Error Wrapping

Use %w when callers need to inspect the underlying error with errors.Is or errors.As. Use %v when you want to hide implementation details or at system boundaries.

// Preserve error chain for programmatic inspection
if err != nil {
    return fmt.Errorf("load config: %w", err)
}

// Hide internal details at API boundaries
if err != nil {
    return fmt.Errorf("database unavailable: %v", err)
}

Keep context succinct. Avoid phrases like "failed to" that pile up as errors propagate.

// Wrong: produces "failed to x: failed to y: failed to create store: the error"
return fmt.Errorf("failed to create new store: %w", err)

// Correct: produces "x: y: new store: the error"
return fmt.Errorf("new store: %w", err)

Joining Multiple Errors (Go 1.20+)

Use errors.Join when multiple operations can fail independently.

var (
    ErrNameRequired  = errors.New("name required")
    ErrEmailRequired = errors.New("email required")
)

func validateUser(u User) error {
    var errs []error
    if u.Name == "" {
        errs = append(errs, ErrNameRequired)
    }
    if u.Email == "" {
        errs = append(errs, ErrEmailRequired)
    }
    return errors.Join(errs...)
}

// errors.Is works on joined errors
if err := validateUser(u); err != nil {
    if errors.Is(err, ErrNameRequired) {
        // matches even when joined with other errors
    }
}