A migration guide from github.com/hashicorp/go-multierror to the std library errors package.

In go1.20 support for “multierrors” was added.

Why migrate? #

Migrating from community go modules to standard library implementations is almost always a no-brainer if it provides like for like functionality.

Packages in the core go standard library such as errors are covered by the go1.0 backwards compatibility guarantee [0].
Because of this they are also guaranteed to be supported with security fixes and other patches.

• https://go.dev/doc/go1compat [0]

APIs #

go-multierror #

go-multierror follows a similar API to how slices are appended to in go.

Playground: https://go.dev/play/p/DrfOauIC1Ou

var result error

if err := step1(); err != nil {
	result = multierror.Append(result, err)
}
if err := step2(); err != nil {
	result = multierror.Append(result, err)
}
if result != nil {
	fmt.Printf("some error: %v", result)
}

multierror.Append returns a *multierror.Error which can be further appended to. And if a multierror is appended to another, they will be flattened to make a flat list of errors.

errors.Join #

The standard library implementation is as a new function in the errors package.

func Join(errs ...error) error

And a new unexported interface.

interface { Unwrap() []error }

Playground: https://go.dev/play/p/D7gFVsBwIbg

err1 := step1()
err2 := step2()
err := errors.Join(err1, err2)
if err != nil {
	return fmt.Error("some error: %w", err)
}

Differences #

Although at a high level the APIs are similar, there is one big difference which is that errors.Join does not flatten other “joined” errors.