Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Go 1.26: go fix rewrites, errors.AsType and go.mod surprises

go fix now modernizes code, errors.AsType compiles instead of panicking, and go mod init writes the previous minor on purpose.

~5 min readGo
#Go#Toolchain#Go Modules#Migration
A fix wand smoothing a Go code block beside a typed error socket, headline GO 1 26

Introduction & Quick Summary

Symptom. You bump the toolchain to Go 1.26 and one of these appears:

go: go.mod requires go >= 1.26.0 (running go 1.25.10; GOTOOLCHAIN=local) ./main.go:24:32: AppError does not satisfy error (method Error has pointer receiver)

Or nothing fails at all, and go mod init in a new repository writes go 1.25.0 into go.mod even though you are running the 1.26 toolchain, so CI on 1.25 resolves different dependency versions than you did locally.

Cause. Three separate 1.26 changes. go fix was rebuilt on the same analysis framework as go vet and now applies a large suite of modernizers, so it rewrites code that was merely old rather than broken. go mod init deliberately writes the previous minor version into new go.mod files, so the module stays buildable on a supported toolchain. And the generic errors.AsType gives you a compile error where errors.As used to panic or silently fail at runtime.

Fix. Let the toolchain manage itself, and adopt AsType at the call sites where reflection used to hurt.

bash
go get go@1.26.0 go get toolchain@go1.26.0
go
// before: reflection, panics on a wrong target var target *AppError if errors.As(err, &target) { fmt.Println("app error:", target) } // after: type-safe, no reflection, no panic on misuse if target, ok := errors.AsType[*AppError](err); ok { fmt.Println("app error:", target) }

Core Mechanics, Signatures & Reproducible Setup

The language change is small: new accepts an expression operand, so new(yearsSince(born)) produces a pointer to the computed value, which is what JSON and protobuf optional fields wanted. Generic types may now refer to themselves in their constraint list, so type Adder[A Adder[A]] interface { Add(A) A } compiles. Neither changes existing code.

The tooling change is the one with teeth. go fix is now the home of the modernizers, built on the Go analysis framework and therefore sharing analyzers with go vet, with a -diff flag for review:

bash
go fix -diff ./... # print a unified diff, change nothing go fix ./... # apply the fixes

Add the go directive deliberately rather than letting a go get do it as a side effect:

bash
go mod edit -go=1.26.0 go mod tidy go vet ./...

Reproduce the go.mod surprise in a temporary directory, which is worth doing once because it changes what "requires Go 1.26" means for consumers:

bash
mkdir /tmp/g26 && cd /tmp/g26 && go mod init example.com/g26 head -3 go.mod # go 1.25.0 with a 1.26 toolchain

That behaviour is intentional: a module created today should compile on the two most recent releases, not only on yours.

Key Comparison Table

API or behaviourBeforeGo 1.26When to change
Error type assertionerrors.As(err, &target)errors.AsType[T](err)new code and hot paths
new with a valuex := f(); &xnew(f())optional serialized fields
Generic constraintsno self referencetype A[B A[B]] interface{}fluent builder interfaces
go fixobsolete pre-1.0 fixersmodernizers, -diffreview on every minor bump
go mod initcurrent versionprevious minoredit with go mod edit -go=
go tool docpresentremoveduse go doc
fmt.Errorf on a plain string2 allocations0 to 1no change needed
errors.Aserrors.AsType
takes any, &targettakes a type parameter
reflection at runtimeno reflection
panics on a non-pointer targetcompile error
about 95 ns per call in benchmarksabout 30 ns per call
works on every versionGo 1.26 and later

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. As and pointer receivers

The most common 1.26 compile error is not new API usage at all: it is AsType rejecting a type that As accepted through reflection. AsType requires the type argument to satisfy error, so a type whose Error() method has a pointer receiver must be used as a pointer:

go
type AppError struct{ Code int } func (e *AppError) Error() string { return "app error" } // errors.AsType[AppError](err) // AppError does not satisfy error errors.AsType[*AppError](err) // correct

The error message names the method and the receiver, which is a better failure than the old runtime panic errors: *target must be interface or implement error.

2. go fix is not go vet

vet reports likely mistakes. fix rewrites code to modern idioms and is designed to be behaviour-preserving, which means it may touch code with no bug in it: interface{} to any, three-clause loops to range over integers, strings.Split loops to strings.Cut. Run it with -diff on a branch and read the patch:

bash
go fix -diff ./... | tee /tmp/gofix.patch git apply --check /tmp/gofix.patch

Two things to look for: a rewrite that changes allocation behaviour in a hot loop, and a rewrite in a file that generated code owns. Exclude generated packages by convention (// Code generated ... DO NOT EDIT.), because a later regeneration will fight the fix.

3. The toolchain directive and CI drift

GOTOOLCHAIN=local pins Go to whatever is installed, so a go.mod that requires 1.26 fails instead of downloading it. In CI that is the right setting; on a laptop it is the reason "it works on mine" and not on the runner:

bash
go env GOTOOLCHAIN GOTOOLCHAIN=auto go build ./... # downloads the version go.mod asks for

Pin the same version in three places — go.mod, the setup-go action, and the Docker builder image — or the difference shows up as a go.sum mismatch.

4. for range int and loop variable semantics

Loop variables are per-iteration since 1.22, and for i := range n has been available since 1.22 as well, so 1.26's modernizer will convert for i := 0; i < n; i++ when the body only uses i. That is safe for the index, but if the body captured i in a closure expecting the old shared variable, the code was already broken by 1.22 and the rewrite merely makes it obvious. Check closures inside converted loops before merging.

5. Removed commands and scripts

cmd/doc and go tool doc are gone; a Makefile line that used them fails with go: no such tool "doc":

bash
# before go tool doc fmt.Errorf # after go doc fmt.Errorf

The flags and arguments are identical, so this is a one-line change per script, but it only fails when that target runs, which may be the release target.

6. vet diagnostics that arrived with the shared analyzers

Because go fix and go vet now share analyzers, a vet run can report a diagnostic that older releases did not, in code you did not touch. Treat a new vet finding as either a real bug or an analyzer improvement, and if it is the latter, keep the finding visible and fix the code: //nolint equivalents do not exist in go vet, so the only way to silence it is to change the code or drop the check from CI.

bash
go vet ./... 2>&1 | grep -v "^#" | sort | uniq -c | sort -rn

Sorting by frequency separates one systemic mistake from noise. Compare the json output of new error values with the JSON formatter when a vet finding concerns struct tags, since a broken tag is invisible in normal output.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Bumping go.mod with go get in the middle of an unrelated change. It drags dependency upgrades along and hides which one broke the build.
  • Running go fix ./... and committing the result unread. It is safe by design, not by guarantee; review the diff.
  • Using AsType with a value type that has pointer receivers. The compile error is correct; change the type argument.
  • Assuming go mod init writes your toolchain version. It writes the previous minor on purpose.
  • Leaving GOTOOLCHAIN=local in CI while go.mod moves ahead. The runner fails with a version message that reads like a dependency problem.
  • Expecting a module created on 1.26 to be usable on 1.25. The go 1.25.0 directive says it is, and go get go@1.26.0 says the opposite; choose deliberately.
  • Trusting a benchmark that compares As and AsType in a non-escaping loop. The allocation difference is real, but measure it in your own hot path.

Reference: Go 1.26 release notes and Using go fix to modernize Go code.

Official references

primary documentation

The Go documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Go guides

More in Go

All Go guides

The guides filed next to this one in Go, in library order.