All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

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

Keep reading