errors

README

errors

Zero-dependency, modern Go error utilities with first-class multi-error support, perfect errors.Is/As/Unwrap interop, and a beautiful API.

Built as a drop-in replacement for the standard errors package + github.com/hashicorp/go-multierror (or go.uber.org/multierr), but without any external dependencies.

---

Features

• New, Errorf, Wrap, and the missing Wrapf everyone wants
• Full multi-error support via a tiny internal multiError type
• Append, Join, Flatten, Prefix, WithMessage, and Errors()
• 100% compatible with fmt.Errorf("%w", ...), errors.Is, errors.As, and errors.Join
• Excellent error formatting (%v and %+v look great)
• Full godoc examples and table-tested behavior
• No runtime allocation surprises

Installation

If this package lives inside your own module:

go get -u github.com/jwm1rr0rb10/go-errors

---

Quick Start

package main

import (
    "fmt"
    "yourmodule/errors" // or "github.com/yourusername/errors"
)

func main() {
    err1 := errors.New("permission denied")
    err2 := errors.New("disk full")

    // Combine multiple errors
    err := errors.Append(err1, err2)
    fmt.Println(err)
    // Output:
    // 2 errors occurred:
    //   - permission denied
    //   - disk full

    // Add context to everything
    err = errors.Prefix(err, "backup failed")
    fmt.Println(err)
    // Output:
    // 2 errors occurred:
    //   - backup failed: permission denied
    //   - backup failed: disk full

    // Causal wrapping (the stdlib way)
    dbErr := errors.New("connection refused")
    err = errors.Wrapf(dbErr, "failed to connect to %s:%d", "db.example.com", 5432)
    fmt.Println(err)
    // Output: failed to connect to db.example.com:5432: connection refused

    // Check errors the normal way
    if errors.Is(err, dbErr) {
        fmt.Println("original db error is still in the chain")
    }
}

API Overview

Function	Description
New(msg string) error	Same as errors.New (never returns nil)
"Errorf(format string, args ...any) error"	Same as fmt.Errorf
"Wrap(err error, msg string) error"	Wrap with context (nil → nil)
"Wrapf(err error, format string, args ...any) error"	Formatted wrap (nil → nil)
"Append(err error, errs ...error) error"	Multi-error builder (nil if all nil)
Join(errs ...error) error	Alias for errors.Join
Flatten(err error) error	Collapse single-error multi-errors
"Prefix(err error, prefix string) error"	Add prefix to every error inside
"WithMessage(err error, msg string) error"	Add sibling message (like old Combine)
Errors(err error) []error,	Extract all underlying errors
"Is, As, Unwrap"	Re-exported stdlib helpers

---

Why this library?

• No dependency hell — unlike go-multierror or multierr
• Modern Go — fully leverages Go 1.20+ errors.Join and %w unwrapping
• Better UX than both HashiCorp and Uber versions
• Beautiful output — multi-errors print cleanly by default
• Zero surprises — every function has clear, documented nil-handling

---

License

MIT License – © Raman Zaitsau @jwm1rrr0rb10

Made with ❤️ for cleaner Go error handling

Documentation

Overview

Package errors provides utilities for creating, wrapping, combining, and inspecting errors.

It is 100% dependency-free and works perfectly with the standard library's errors package (Go 1.20+). Multi-errors support errors.Is, errors.As, and errors.Unwrap out of the box.

Index

• func Append(err error, errs ...error) error
• func As(err error, target any) bool
• func Errorf(format string, args ...any) error
• func Errors(err error) []error
• func Flatten(err error) error
• func Is(err, target error) bool
• func Join(errs ...error) error
• func New(msg string) error
• func Prefix(err error, prefix string) error
• func Unwrap(err error) error
• func WithMessage(err error, msg string) error
• func Wrap(err error, msg string) error
• func Wrapf(err error, format string, args ...any) error

Examples

• Errors
• Prefix
• Wrapf

Functions

func Append

func Append(err error, errs ...error) error

Append combines multiple errors into a multi-error. Returns nil if all errors are nil.

func As

func As(err error, target any) bool

func Errorf

func Errorf(format string, args ...any) error

Errorf creates a formatted error. Use %w to wrap another error.

func Errors

func Errors(err error) []error

Errors returns the list of underlying errors. If err is not a multi-error, returns a single-element slice.

Example

package main

import (
	"fmt"

	"github.com/jwm1rr0rb10/go-errors"
)

func main() {
	err := errors.Append(
		errors.New("validation failed"),
		errors.New("user already exists"),
	)
	for _, e := range errors.Errors(err) {
		fmt.Println(e)
	}
}

Output:
validation failed
user already exists

func Flatten

func Flatten(err error) error

Flatten returns a single error if the multi-error contains only one error. Otherwise returns the multi-error unchanged.

func Is

func Is(err, target error) bool

func Join

func Join(errs ...error) error

Join is an alias for errors.Join (stdlib).

func New

func New(msg string) error

New creates a new error with the given message (never returns nil).

func Prefix

func Prefix(err error, prefix string) error

Prefix adds the same prefix to every error inside err (works for both single errors and multi-errors).

Example

package main

import (
	"fmt"

	"github.com/jwm1rr0rb10/go-errors"
)

func main() {
	err1 := errors.New("permission denied")
	err2 := errors.New("disk full")
	err := errors.Append(err1, err2)
	err = errors.Prefix(err, "backup failed")
	fmt.Println(err)
}

Output:
2 errors occurred:
  - backup failed: permission denied
  - backup failed: disk full

func Unwrap

func Unwrap(err error) error

Unwrap, Is, and As are re-exported for convenience.

func WithMessage

func WithMessage(err error, msg string) error

WithMessage adds msg as a sibling error. If err is nil, returns a plain error with msg.

func Wrap

func Wrap(err error, msg string) error

Wrap wraps err with additional context. If err is nil, returns nil.

func Wrapf

func Wrapf(err error, format string, args ...any) error

Wrapf wraps err with a formatted message. If err is nil, returns nil.

Example

package main

import (
	"fmt"

	"github.com/jwm1rr0rb10/go-errors"
)

func main() {
	err := errors.New("connection refused")
	err = errors.Wrapf(err, "failed to dial %s:%d", "db.example.com", 5432)
	fmt.Println(err)
}

Output:
failed to dial db.example.com:5432: connection refused