go-multierror

go-multierror is a small HashiCorp-maintained Go package that represents a list of error values as a single error. It lets a function accumulate several failures during a multi-step operation and return them all as one value, instead of stopping at the first error or requiring a custom error type. Callers that don’t know about multierror still get a readable, formatted error string; callers that do can type-assert to *multierror.Error and access the underlying Errors slice directly.

The package is fully compatible with the standard library errors package, implementing Unwrap, Is, and As so that errors.Is/errors.As traverse each wrapped error correctly. It also ships a Group type for coalescing errors from concurrent goroutines, plus Append, Flatten, and Prefix helpers for building and reshaping error lists. As of Go 1.20, the standard library’s errors.Join covers the basic aggregation case, and the README explicitly recommends it for new projects — go-multierror remains relevant where custom formatting, the Group pattern, or the existing Append/Flatten/Prefix API surface are needed.

What You Get

• Append(err, errs...) — builds or extends a *multierror.Error from any error value, flattening nested multierrors one level
• *multierror.Error implementing the standard error interface plus Unwrap/Is/As for errors package interop
• Customizable ErrorFormat function to control how the combined error renders as a string
• Group — a sync.WaitGroup-backed helper that coalesces errors returned by concurrent goroutines
• Flatten and Prefix helpers for merging nested multierrors and annotating every wrapped error with a common prefix

Common Use Cases

• Running several independent validation checks and reporting all failures in one response instead of stopping at the first
• Fanning work out across goroutines with Group and collecting every failure once all of them finish
• Aggregating per-resource errors in infrastructure tooling (e.g. Terraform providers, HashiCorp tooling) where one API call touches many resources
• Wrapping a batch of cleanup or teardown steps so callers can see everything that went wrong, not just the last error

Under The Hood

Architecture

The package is a flat, single-package library with no internal boundaries: each file owns one orthogonal concern operating on the same *Error struct. multierror.go defines the core Error type (an Errors []error slice plus a pluggable ErrorFormat hook) along with its Error(), Unwrap(), GoString(), and WrappedErrors() methods, and a private chain type that makes errors.Is/errors.As traverse every wrapped error deterministically rather than only the first. append.go builds and flattens error lists one level deep, group.go layers a mutex-guarded sync.WaitGroup around Append for concurrent goroutine result collection, and format.go, flatten.go, prefix.go, and sort.go each add one composable utility. There is no dependency injection or external state; every function is a pure transformation of an error value, so the design surface is small and the core Error struct is the single point every other file depends on.

Tech Stack

go.mod declares Go 1.13 as the minimum version and an empty go.sum — the library has zero third-party dependencies, relying only on the standard library (errors, fmt, strings, sync). A Makefile wraps go test, and CI (.github/workflows/go-multierror.yml) runs a go fmt check plus the test suite on every push and pull request, with a separate actionlint.yml workflow linting the GitHub Actions files themselves. As a leaf library with no runtime dependencies, it’s consumed purely via go get with no deployment or database concerns of its own.

Code Quality

Every source file has a matching _test.go counterpart (covering Error, Append, Group, ListFormatFunc, Flatten, Prefix, and sort.Interface), written with the standard testing package and reflect.DeepEqual/t.Fatalf assertions rather than a third-party assertion library. Error handling is idiomatic Go — values are returned directly, and the core type explicitly implements Unwrap/Is/As so failures stay introspectable instead of being collapsed into strings. Naming is short and consistent (Append, Flatten, Prefix, Group), and CI enforces go fmt plus the full test suite, though there is no additional static-analysis linter (e.g. golangci-lint) configured beyond formatting.

What Makes It Unique

go-multierror doesn’t introduce a novel error-handling model — it’s a straightforward “slice of errors wrapped in one error” pattern, and the README itself now points new projects at the standard library’s errors.Join (Go 1.20+) for the basic aggregation case, including a migration guide. What it still offers beyond stdlib is narrower but genuine: the Group helper for concurrent error collection (deliberately absent from errgroup, which returns only the first error), a configurable ErrorFormat for custom rendering, and Flatten/Prefix utilities with no direct standard-library equivalent.