# Replace pkg/errors With the Standard Library in a Go Module

Yes. An agent rewrites pkg/errors calls to fmt.Errorf with %w and the standard errors package, and shows which messages and stack traces change.

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

## What the agent does

Since Go 1.13 the standard library wraps errors itself, and the README of `github.com/pkg/errors` says the package is moving into maintenance mode. The agent's first step is a count by function, because each one ports differently. In a library like ulule/limiter, `go.mod` requires `github.com/pkg/errors v0.9.1` and two files import it. `rate.go` has three `errors.Errorf` calls for a rate string it cannot parse. `drivers/store/redis/store.go` has three `errors.Wrap` calls around Redis failures and two `errors.New`. There is no `errors.Cause`, no `WithStack` and no `%+v` anywhere in the module.

The rewrite is small: `errors.Errorf` becomes `fmt.Errorf`, `errors.New` stays the same call from the standard `errors` package, and `errors.Wrap(err, "msg")` becomes `fmt.Errorf("msg: %w", err)`. One difference needs a look at every site. `errors.Wrap` returns nil when given a nil error, and `fmt.Errorf` never does, so a wrap that is not guarded by `if err != nil` would start returning an error on success. All three in this store sit inside such a check, and the agent states that for each line it changes.

What a caller can observe is then measured, not argued. Before editing, the agent adds a temporary test that prints an error from `NewRateFromFormatted("10-X")` with `%v` and with `%+v`, and one that builds the Redis store against a closed port and asks `errors.As` for a `*net.OpError`. With pkg/errors the `%+v` output is the message followed by a stack trace; afterwards it is the message alone. The `%v` text is identical in both, `incorrect period 'X'`, and `errors.As` finds the network error in both, because v0.9.1 already implements `Unwrap`.

The store's tests need a Redis server. `scripts/test` starts one with `docker run` through `scripts/redis` unless `REDIS_DISABLE_BOOTSTRAP` is set, and the sandbox has no Docker. The agent installs `redis-server` with apt, starts it on a spare port, exports `REDIS_URI` and that variable, and runs `go test` over the packages the script lists. After `go mod tidy` the module is gone from `go.mod` and from `go.sum`, since nothing else in the dependency graph needs it, and the `go 1.17` line stays as it is.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Remove github.com/pkg/errors from this Go module and use the standard library instead. List every file that imports it and count the calls by function: New, Errorf, Wrap, Wrapf, WithMessage, WithStack, Cause, Is, As, and any use of the stackTracer interface or the %+v verb on an error. Before editing, run the tests and add a temporary test that prints two representative errors with %v and %+v and checks errors.Is or errors.As through a wrapped error. Then port: fmt.Errorf with %w for Wrap, Wrapf and WithMessage, errors.New and fmt.Errorf for New and Errorf, errors.Is, errors.As or errors.Unwrap for Cause. For every Wrap you change, check whether the error can be nil at that point and keep the nil result if it can. Do not change any message text. If code or logging depended on stack traces, say where and leave that call alone. If the tests need a service such as Redis, install it with apt and start it; do not use Docker. Run go mod tidy, go vet and the full tests, rerun the temporary test, then delete it. Open a pull request with the call count, the before and after output and every command you ran.",
  "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 touching `rate.go`, `drivers/store/redis/store.go`, `go.mod` and `go.sum`. Its description has the call count per file, the nil check for each `Wrap`, and the probe output from both sides: the same `%v` strings, a nine-line `%+v` before and a one-line `%+v` after, and `errors.As` succeeding in both.

The reviewer decides one thing: whether anyone downstream prints these errors with `%+v` to get a stack. Inside this module nobody does, but a library's callers are not in the repository, and the description names the loss plainly so it can go in the changelog. They also confirm the Redis-backed tests ran. The description shows the server the agent started, the environment variables it set and the exact `go test` line, including whether the `-race` flag from `scripts/test` was kept.

## Run it on every issue labelled tech-debt

This is the kind of cleanup that sits in a tracker for a year. Add an automation on the Project with a `github` trigger on `issues.labeled`, set its `labels` filter to the label your team uses, and save the prompt above. When a member or collaborator adds the label, a run starts with the issue appended after the prompt, so a note in the issue such as a package to leave alone reaches the agent as context.

If the same dependency is spread over many modules, call `POST /o/{org}/sessions` once per repository from a script instead. Give each call a `request_id` that is a UUID v5 of the repository name, and read each result from `GET /o/{org}/sessions/{id}`, or from the `run.completed` webhook when the key has a `webhook_url`.

## Why run it on Rush?

A search and replace gets this change to compile in minutes, which is the problem: the two behaviours that differ, nil passing through `Wrap` and stack traces in `%+v`, both compile either way. The agent prints real errors from the real code before and after and keeps that output with the run, so the difference a caller would see is on the page before anyone merges.

It also needs a live Redis to run the store's tests, started and stopped without touching a shared instance. The sandbox is a disposable machine for exactly that; the server the agent installs disappears with it, and the test output stays in the transcript.

## Frequently asked questions

### Do I lose stack traces when I drop pkg/errors?

Yes. `fmt.Errorf` records no stack, so `%+v` prints only the message chain. If you rely on traces in logs, keep the package at the few sites that need one or log the stack where the error is handled; the agent lists every `%+v` and `StackTrace` use it finds so you can decide before the port.

### Is errors.Wrap(err, msg) the same as fmt.Errorf with %w?

The message is the same, `msg: cause`, and `errors.Is` and `errors.As` see through both. Two things differ: `Wrap` returns nil for a nil error where `fmt.Errorf` returns a new error, and `Wrap` attaches a stack. The agent checks the first at each call and reports the second.

### What replaces errors.Cause?

Usually `errors.Is` for a sentinel value or `errors.As` for a type, which is what callers of `Cause` were about to do with the result. A loop over `errors.Unwrap` gives the innermost error when the code really wants the root.

### Does this need a newer Go version?

Only Go 1.13 or later, where `%w`, `errors.Is` and `errors.As` first appeared. This module declares `go 1.17`, so the directive does not move and no CI image changes.

## More jobs like this: Upgrade dependencies weekly

- [Fix "No module named 'pkg_resources'" by Migrating to importlib.resources](https://getrush.ai/run/migrate-pkg-resources-to-importlib-resources/setuptools/)
- [Migrate a Flask App From psycopg2 to Psycopg 3](https://getrush.ai/run/migrate-psycopg2-to-psycopg3/psycopg2/)
- [Migrate From PyPDF2 to pypdf and Fix "PdfFileReader is deprecated and was removed"](https://getrush.ai/run/migrate-pypdf2-to-pypdf/pypdf2/)
- [Migrate From python-jose to PyJWT in a FastAPI App](https://getrush.ai/run/migrate-python-jose-to-pyjwt/python-jose/)
- [Migrate From raven to sentry-sdk in a Django App](https://getrush.ai/run/migrate-raven-to-sentry-sdk/raven/)
- [Migrate From React Query v3 to TanStack Query v5](https://getrush.ai/run/migrate-react-query-to-tanstack-query/react-query/)

## 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/)
