go-multierror

A Go (golang) package for representing a list of errors as a single error.

2,297

123

2,297

View on GitHub

Top Related Projects

errorx

1,118

A comprehensive error handling library for Go

eris

1,485

Error handling library with readable stack traces and flexible formatting support 🎆

Quick Overview

go-multierror is a Go library that provides a way to represent and handle multiple errors as a single error. It allows developers to accumulate errors and treat them as a single entity, which is particularly useful in scenarios where multiple operations can fail independently.

Pros

Simplifies error handling in complex operations
Provides a clean API for accumulating and accessing multiple errors
Supports custom formatting of error messages
Compatible with standard Go error interfaces

Cons

May encourage less granular error handling in some cases
Potential overhead for simple error scenarios
Limited built-in error categorization or prioritization

Code Examples

Example 1: Creating and appending errors

import "github.com/hashicorp/go-multierror"

var result error

if err := operation1(); err != nil {
    result = multierror.Append(result, err)
}

if err := operation2(); err != nil {
    result = multierror.Append(result, err)
}

if result != nil {
    // Handle multiple errors
    fmt.Println(result.Error())
}

Example 2: Using a custom error format

import "github.com/hashicorp/go-multierror"

errors := []error{
    errors.New("error 1"),
    errors.New("error 2"),
}

err := multierror.Append(nil, errors...)
err.ErrorFormat = func([]error) string {
    return "Multiple errors occurred"
}

fmt.Println(err.Error()) // Output: Multiple errors occurred

Example 3: Flattening nested multierrors

import "github.com/hashicorp/go-multierror"

err1 := multierror.Append(nil, errors.New("error 1"), errors.New("error 2"))
err2 := multierror.Append(nil, errors.New("error 3"), err1)

flat := multierror.Flatten(err2)
fmt.Println(len(flat.Errors)) // Output: 3

Getting Started

To use go-multierror in your Go project:

Install the package:

go get github.com/hashicorp/go-multierror

Import the package in your Go code:

import "github.com/hashicorp/go-multierror"

Start using the multierror functionality:

var result error
result = multierror.Append(result, errors.New("error 1"))
result = multierror.Append(result, errors.New("error 2"))

if result != nil {
    fmt.Println(result.Error())
}

Competitor Comparisons

errorx

1,118

A comprehensive error handling library for Go

Pros of errorx

More comprehensive error handling with rich context and type hierarchy
Built-in error types for common scenarios (e.g., timeout, not found)
Supports error wrapping and unwrapping with additional metadata

Cons of errorx

Steeper learning curve due to more complex API
Potentially higher memory usage for storing additional error context
May be overkill for simpler projects with basic error handling needs

Code Comparison

errorx:

err := errorx.Decorate(originalError, "additional context")
if errorx.IsOfType(err, errorx.NotFound) {
    // Handle not found error
}

go-multierror:

var result error
result = multierror.Append(result, err1)
result = multierror.Append(result, err2)

Summary

errorx offers a more feature-rich error handling solution with built-in error types and extensive context support, while go-multierror focuses on combining multiple errors into a single error value. errorx may be better suited for larger projects requiring detailed error information, while go-multierror provides a simpler approach for aggregating errors in concurrent operations or validation scenarios.

eris

1,485

Error handling library with readable stack traces and flexible formatting support 🎆

Pros of eris

Provides more detailed error information, including stack traces and root cause analysis
Offers a wider range of error wrapping and formatting options
Includes built-in support for error classification and custom error types

Cons of eris

May have a steeper learning curve due to its more extensive feature set
Potentially higher memory usage when capturing stack traces for all errors

Code Comparison

eris:

err := eris.New("base error")
wrappedErr := eris.Wrap(err, "additional context")
fmt.Println(eris.ToString(wrappedErr, true))

go-multierror:

var result error
result = multierror.Append(result, errors.New("error 1"))
result = multierror.Append(result, errors.New("error 2"))
fmt.Println(result.Error())

eris focuses on providing rich error context and stack traces, while go-multierror primarily deals with aggregating multiple errors. eris offers more comprehensive error handling capabilities, but may require more setup and understanding to use effectively. go-multierror is simpler and more straightforward for basic error aggregation needs, but lacks advanced features like stack trace capture and error classification.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

go-multierror

GitHub go.mod Go version

go-multierror is a package for Go that provides a mechanism for representing a list of error values as a single error.

This allows a function in Go to return an error that might actually be a list of errors. If the caller knows this, they can unwrap the list and access the errors. If the caller doesn't know, the error formats to a nice human-readable format.

go-multierror is fully compatible with the Go standard library errors package, including the functions As, Is, and Unwrap. This provides a standardized approach for introspecting on error values.

Installation and Docs

Install using go get github.com/hashicorp/go-multierror.

Full documentation is available at https://pkg.go.dev/github.com/hashicorp/go-multierror

Requires go version 1.13 or newer

go-multierror requires go version 1.13 or newer. Go 1.13 introduced error wrapping, which this library takes advantage of.

If you need to use an earlier version of go, you can use the v1.0.0 tag, which doesn't rely on features in go 1.13.

If you see compile errors that look like the below, it's likely that you're on an older version of go:

/go/src/github.com/hashicorp/go-multierror/multierror.go:112:9: undefined: errors.As
/go/src/github.com/hashicorp/go-multierror/multierror.go:117:9: undefined: errors.Is

Usage

go-multierror is easy to use and purposely built to be unobtrusive in existing Go applications/libraries that may not be aware of it.

Building a list of errors

The Append function is used to create a list of errors. This function behaves a lot like the Go built-in append function: it doesn't matter if the first argument is nil, a multierror.Error, or any other error, the function behaves as you would expect.

var result error

if err := step1(); err != nil {
	result = multierror.Append(result, err)
}
if err := step2(); err != nil {
	result = multierror.Append(result, err)
}

return result

Customizing the formatting of the errors

By specifying a custom ErrorFormat, you can customize the format of the Error() string function:

var result *multierror.Error

// ... accumulate errors here, maybe using Append

if result != nil {
	result.ErrorFormat = func([]error) string {
		return "errors!"
	}
}

Accessing the list of errors

multierror.Error implements error so if the caller doesn't know about multierror, it will work just fine. But if you're aware a multierror might be returned, you can use type switches to access the list of errors:

if err := something(); err != nil {
	if merr, ok := err.(*multierror.Error); ok {
		// Use merr.Errors
	}
}

You can also use the standard errors.Unwrap function. This will continue to unwrap into subsequent errors until none exist.

Extracting an error

The standard library errors.As function can be used directly with a multierror to extract a specific error:

// Assume err is a multierror value
err := somefunc()

// We want to know if "err" has a "RichErrorType" in it and extract it.
var errRich RichErrorType
if errors.As(err, &errRich) {
	// It has it, and now errRich is populated.
}

Checking for an exact error value

Some errors are returned as exact errors such as the ErrNotExist error in the os package. You can check if this error is present by using the standard errors.Is function.

// Assume err is a multierror value
err := somefunc()
if errors.Is(err, os.ErrNotExist) {
	// err contains os.ErrNotExist
}

Returning a multierror only if there are errors

If you build a multierror.Error, you can use the ErrorOrNil function to return an error implementation only if there are errors to return:

var result *multierror.Error

// ... accumulate errors here

// Return the `error` only if errors were added to the multierror, otherwise
// return nil since there are no errors.
return result.ErrorOrNil()

Top Related Projects

errorx

1,118

A comprehensive error handling library for Go

eris

1,485

Error handling library with readable stack traces and flexible formatting support 🎆

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot