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.

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.
go get go@1.26.0
go get toolchain@go1.26.0// 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:
go fix -diff ./... # print a unified diff, change nothing
go fix ./... # apply the fixesAdd the go directive deliberately rather than letting a go get do it as a side effect:
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:
mkdir /tmp/g26 && cd /tmp/g26 && go mod init example.com/g26
head -3 go.mod # go 1.25.0 with a 1.26 toolchainThat behaviour is intentional: a module created today should compile on the two most recent releases, not only on yours.
Key Comparison Table
| API or behaviour | Before | Go 1.26 | When to change |
|---|---|---|---|
| Error type assertion | errors.As(err, &target) | errors.AsType[T](err) | new code and hot paths |
new with a value | x := f(); &x | new(f()) | optional serialized fields |
| Generic constraints | no self reference | type A[B A[B]] interface{} | fluent builder interfaces |
go fix | obsolete pre-1.0 fixers | modernizers, -diff | review on every minor bump |
go mod init | current version | previous minor | edit with go mod edit -go= |
go tool doc | present | removed | use go doc |
fmt.Errorf on a plain string | 2 allocations | 0 to 1 | no change needed |
errors.As | errors.AsType |
|---|---|
takes any, &target | takes a type parameter |
| reflection at runtime | no reflection |
| panics on a non-pointer target | compile error |
| about 95 ns per call in benchmarks | about 30 ns per call |
| works on every version | Go 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:
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) // correctThe 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:
go fix -diff ./... | tee /tmp/gofix.patch
git apply --check /tmp/gofix.patchTwo 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:
go env GOTOOLCHAIN
GOTOOLCHAIN=auto go build ./... # downloads the version go.mod asks forPin 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":
# before
go tool doc fmt.Errorf
# after
go doc fmt.ErrorfThe 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.
go vet ./... 2>&1 | grep -v "^#" | sort | uniq -c | sort -rnSorting 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.modwithgo getin 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
AsTypewith a value type that has pointer receivers. The compile error is correct; change the type argument. - Assuming
go mod initwrites your toolchain version. It writes the previous minor on purpose. - Leaving
GOTOOLCHAIN=localin CI whilego.modmoves 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.0directive says it is, andgo get go@1.26.0says the opposite; choose deliberately. - Trusting a benchmark that compares
AsandAsTypein 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 documentationThe Go documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Go guides
All Go guidesGo: panic: assignment to entry in nil map
Reads on a nil map are legal, writes panic. Initialise in a constructor, allocate inner maps, and do not confuse this with a concurrent write.
Go: invalid memory address or nil pointer dereference
Most nil panics are a typed nil in an interface or a value used after an error. How each shape fails, how to return nil properly, and which stack trace detail names the cause.
missing go.sum entry and inconsistent vendoring: Go Module Fixes
Readonly module mode will not repair your files. go mod tidy fixes the checksums, go mod vendor fixes the tree, and neither belongs in CI as a workaround.
Go http.Client: unexpected EOF and Connection Reuse Leaks
A body closed without being read cannot be reused, and descriptors pile up. Idle timeouts shorter than the upstream's, MaxIdleConnsPerHost and safe retries.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.