# Replace hashicorp/go-multierror With errors.Join in a Go Project

Yes. An agent replaces go-multierror with the standard library's errors.Join, shows how error text and nil handling change, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-go-multierror-to-errors-join/go-multierror/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Go 1.20 added `errors.Join`, and for code that only collects errors it removes the need for `github.com/hashicorp/go-multierror`. The agent starts by finding out whether the code only collects. In a project like SenseUnit/dumbproxy, `go.mod` requires `go-multierror` v1.1.1 directly and `hashicorp/errwrap` indirectly, and the package is used in seven files: `auth/cert.go`, `auth/redis.go`, `auth/tlscookie.go`, `dialer/hintdialer.go`, `dialer/resolve.go`, `dialer/pipewrap.go` and `resolver/fast.go`. Every use is `multierror.Append`. There is no `ErrorOrNil`, no read of the `Errors` slice, no custom `ErrorFormat` and no `Group`. That is the easy case, and the agent says so before it edits; a codebase that formats or iterates the collected errors gets a longer plan.

The rewrite is `errors.Join(err, closeErr)` for each `multierror.Append(err, closeErr)`, plus the import. Three of the seven files already import `errors`, and four need it added. One file does not compile after the mechanical change. In `resolver/fast.go`, `LookupNetIP` declares `errors := make(chan error)`, which shadows the package inside that function, and the compiler answers `errors.Join undefined (type chan error has no field or method Join)`. The agent renames the channel in the three places it appears. The repository also has a package of its own at `dialer/errors`, so the agent reads each import block instead of assuming what the name refers to.

The two helpers do not behave the same, and the agent writes a small program that prints the differences instead of describing them from memory. The text changes: two collected errors print under go-multierror as `2 errors occurred:` followed by a tab-indented, starred line per error, and under `errors.Join` as the two messages separated by a newline, with no header. A single error prints bare. In `dialer/resolve.go` that string is wrapped by `fmt.Errorf("failed to dial %s: %w", address, dialErr)`, so this is the text that reaches the caller when every address fails. Nil handling changes as well: `multierror.Append(nil, nil)` returns a non-nil value, while `errors.Join(nil, nil)` returns nil. Each call site here appends only after a non-nil check, so nothing depends on that, and the agent lists the sites to show it.

What stays the same is matching. `errors.Is` and `errors.As` see through both, which matters in `dialer/resolve.go`, where the loop already calls `errors.As` on each dial error. The agent runs `gofmt`, `go build ./...`, `go vet ./...` and `go test ./...` before and after, then `go mod tidy`, and confirms that both `go-multierror` and `errwrap` are gone from `go.mod` and `go.sum`. The packages it edited have little test coverage of these paths, so it adds tests for a `Close` method whose two children both fail and for the resolver's all-upstreams-fail case, asserting with `errors.Is` and not on message text.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace github.com/hashicorp/go-multierror with the standard library's errors.Join in this Go module. Read go.mod for the Go version (errors.Join needs 1.20) and for whether go-multierror and errwrap are direct or indirect. List every use by kind: Append, ErrorOrNil, the Errors field, ErrorFormat, Group, Prefix, Flatten, and any type assertion to *multierror.Error. If the code uses ErrorFormat, Group or iterates Errors, propose the equivalent before changing it and keep behaviour the same. Write a small Go program that prints, for go-multierror and errors.Join side by side: the message for one and for two collected errors, the message when wrapped with %w, the result of joining only nil values compared with nil, and whether errors.Is and errors.As match an inner error. Include its output in the pull request. For each call site, say whether a nil could be appended and whether any caller compares the message text. Make the change, adding the errors import where missing, and check each file for a local variable or project package named errors that shadows the standard one; rename the local, not the import. Run gofmt, go build, go vet and go test on every package before and after, and report vet findings that exist in files you did not touch as pre-existing. Run go mod tidy and show that go-multierror and errwrap are gone, or run go mod why to explain what still needs them. Add tests for the edited code paths that assert with errors.Is, not on message strings. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that edits the seven files, `go.mod` and `go.sum`, and adds tests. The description leads with the output of the comparison program, because the visible effect of this change is in log lines: the header and the starred list are gone, and each failed attempt is on its own line. It names the wrapped message in `dialer/resolve.go` as the place where the new text surfaces. It includes the compile error from `resolver/fast.go` and the rename that fixed it, so the reason for a diff in a line that never mentioned multierror is on record.

The reviewer checks for anything that reads error text: a log parser, an alert rule that matches `errors occurred`, a test that compares strings. The agent searches the repository for those and reports none or lists them; it cannot see a log pipeline outside the repository, and says so. The reviewer also looks at the `go vet` section. Findings in files this change does not touch are listed separately as pre-existing, with their file and line, and are not fixed here.

## Run it on every package in the module

A module with dozens of call sites is easier to review one package at a time, and a run does not have to end after one. Start with this body and a first sentence narrowed to one directory, for example `auth`. When that turn finishes, the sandbox parks with its disk, so the module cache and build cache are still there. Send the next directory as a follow-up, `POST /o/{org}/sessions/{id}/messages` with `{"input": "Now do the dialer package the same way."}`, and the same sandbox wakes where it left off.

The follow-up answers `202` with the session and the turn it opened. Wait on that turn, not on the session, since the session can still show the previous answer until the queued message runs. A parked sandbox is kept for 7 idle days, which is long enough to review one pull request before asking for the next.

## Why run it on Rush?

This is a change where reading the two libraries' documentation gets you most of the way and the remainder is what breaks. The shadowed `errors` name in one function is not something a search for `multierror` finds; the compiler finds it. The run builds, vets and tests every package in its own sandbox with the Go version `go.mod` asks for, and each command's output is kept in the session transcript.

The behaviour differences are shown, not asserted. The comparison program runs both implementations on the same errors and prints the strings, the nil results and the `errors.Is` answers. A reviewer deciding whether a changed log format is acceptable is looking at the exact new format, produced by the code in the pull request.

## Frequently asked questions

### Does errors.Join work with errors.Is and errors.As?

Yes. The value it returns has an `Unwrap() []error` method, and `errors.Is` and `errors.As` check every error in that list. Code that matched a sentinel or a typed error inside a go-multierror value keeps matching after the change.

### How does the error message differ?

go-multierror prints a count line such as `2 errors occurred:` and then each error on a tab-indented line starting with `*`. `errors.Join` prints each error's message on its own line with nothing added. If you need the old layout, format it yourself from the list that `Unwrap() []error` returns.

### What replaces ErrorOrNil?

Nothing is needed. `errors.Join` skips nil arguments and returns nil when every argument is nil, so `return errors.Join(errs...)` is already correct. With go-multierror, `Append` returns a non-nil value even when no real error was added, which is why `ErrorOrNil` existed.

### Can I still get the individual errors back?

Yes, with a type assertion: `err.(interface{ Unwrap() []error })`. Note that `errors.Join` does not flatten. Joining an already joined error with a third gives a list of two, the first of which holds two more, where go-multierror would give a flat list of three.

### Which Go version does this need?

Go 1.20 or newer, for `errors.Join` and for multiple `%w` verbs in `fmt.Errorf`. The agent reads the `go` directive in `go.mod` first and stops with a report if the module still targets an older release.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From go-redis v8 to v9 (github.com/redis/go-redis/v9)](https://getrush.ai/run/migrate-go-redis-v8-to-v9/go-redis/)
- [Replace mattn/go-sqlite3 With modernc.org/sqlite for a cgo-Free Go Build](https://getrush.ai/run/migrate-go-sqlite3-to-modernc-sqlite/go-sqlite3/)
- [Migrate From gopkg.in/yaml.v2 to yaml.v3 in a Go Project](https://getrush.ai/run/migrate-go-yaml-v2-to-v3/go-yaml/)
- [Migrate From github.com/golang/protobuf to google.golang.org/protobuf](https://getrush.ai/run/migrate-golang-protobuf-to-google-protobuf/golang-protobuf/)
- [Replace Deprecated golint With revive, go vet and staticcheck in a Go Project](https://getrush.ai/run/migrate-golint-to-revive/golint/)
- [Migrate a Custom Environment From OpenAI Gym to Gymnasium](https://getrush.ai/run/migrate-gym-to-gymnasium/gym/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
