Post

go: error loading go.mod: removed GODEBUG "asynctimerchan" set to old value "1" after upgrading to Go 1.27

Go 1.27 removed the asynctimerchan GODEBUG setting, so a godebug line in go.mod (or a go:debug comment) that sets it to 1 now stops the build. Delete the line, then fix the code that quietly relied on buffered timer channels.

go: error loading go.mod: removed GODEBUG "asynctimerchan" set to old value "1" after upgrading to Go 1.27

If a build that worked on Go 1.26 now stops on Go 1.27 with this:

1
2
go: error loading go.mod:
go.mod:5: removed GODEBUG "asynctimerchan" set to old value "1" (https://go.dev/doc/godebug#go-127)

the cause is a single line in your go.mod: godebug asynctimerchan=1. That setting switched time.Timer and time.Ticker channels back to the pre-1.23 buffered behavior, and Go 1.27 deleted the setting. The fix is to delete the line. The part worth your time is what happens next, because the code that needed the line may now misbehave without any error. Versions tested: Go 1.22.12, 1.23.12, 1.26.0 and 1.27.3 on macOS arm64.

What the error means

Go 1.23 made the channels created by the time package synchronous (unbuffered, capacity 0) and kept an escape hatch, the asynctimerchan setting, for programs that depended on the old buffered channel. The GODEBUG history says the setting "will be removed in Go 1.27", and Go 1.27 did exactly that: its release notes state that channels created by package time are now always unbuffered, "irrespective of GODEBUG settings".

What is new in 1.27 is how the go command treats a setting that no longer exists. Per the release notes it now recognizes a removed setting in godebug entries of go.mod and in //go:debug comments. It accepts the setting if it is set to the final default value, and "if they are set to an old value, the go command will fail".

The error comes in two spellings, depending on where the value lives.

Reproduce it from a clean directory

1
2
3
4
5
6
// go.mod
module example.com/atc

go 1.23

godebug asynctimerchan=1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// main.go
package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.NewTimer(10 * time.Millisecond)
	time.Sleep(50 * time.Millisecond) // the timer has fired, nobody received
	fmt.Println("len before Stop:", len(t.C))
	t.Stop()
	select {
	case <-t.C:
		fmt.Println("stale value received after Stop")
	default:
		fmt.Println("channel empty after Stop")
	}
}

On Go 1.27.3, go run . prints the error at the top of this post and exits before compiling anything. Putting //go:debug asynctimerchan=1 above the package clause of main.go and removing the go.mod line gives the sibling error from the same check:

1
./main.go:1:1: invalid //go:debug: removed GODEBUG "asynctimerchan" set to old value "1" (https://go.dev/doc/godebug#go-127)

Setting the value to 0, which is the final default, is accepted, but it changes nothing: deleting the line is the real fix.

The fix, and what quietly changes

Delete the godebug asynctimerchan=1 line (or the //go:debug comment). With it gone, go run . builds on 1.27.3 and prints:

1
2
len before Stop: 0
channel empty after Stop

The same program run under the toolchain that still honored the setting (Go 1.26.0 with the godebug line present) prints:

1
2
len before Stop: 1
stale value received after Stop

That difference is the whole story. Under the old semantics the fired timer had pushed a value into a buffer of capacity 1, so len(t.C) was 1, and a value could be received even after Stop returned. The documentation for time.NewTimer says the same thing in prose: before Go 1.23 the channel was "asynchronous (buffered, capacity 1)", "which meant that stale time values could be received even after Timer.Stop or Timer.Reset returned".

A second trap: no setting, but an old go line

You do not need the setting to be affected. The Go toolchain picks GODEBUG defaults from the go line of the main module, so a module that says go 1.22 used to get the old async channels automatically. That default is gone with the setting. Take the same main.go and a go.mod with only go 1.22:

Toolchaingo linelen(t.C)After Stop
Go 1.22.121.221stale value received
Go 1.23.121.230channel empty
Go 1.27.31.220channel empty

The last row is the one that surprises people: on 1.27 the old go line no longer buys the old behavior, and nothing reports it. No error, no vet warning, just different timing semantics in a module that never touched GODEBUG.

Code that relied on the old channel

Two idioms depended on the buffer. Both can be found with a search for t.C, .C) and Stop() in your tree.

The first is the unconditional drain after Stop. Written for Go 1.22 and older, it stops the timer and empties the buffer so a later Reset starts clean:

1
2
t.Stop()
<-t.C // blocks forever on Go 1.23+ semantics if nothing was buffered

Run against a timer that has already fired, this receives instantly on Go 1.22.12 (the buffer holds the value; cap(t.C) is 1). On Go 1.27.3 the channel has capacity 0 and the receive blocks, which a test showed by racing the receive against a time.After of 200 ms: only the timeout case ever fires. In production that is a goroutine stuck forever on a path that used to be quick.

The guarded variant, if !t.Stop() { <-t.C }, is safe on both sides. With the new semantics Stop is documented to return true whenever "the program has not received from t.C already and the timer is running", and the tested run agrees: the same fired-but-unreceived timer made Stop return false on Go 1.22.12 (so the drain ran and found a value) and true on 1.23.12, 1.26.0 and 1.27.3 (so the drain is skipped).

The second idiom is polling the buffer: len(t.C) > 0 as a cheap "has it fired" check. With capacity 0 that is always zero, so the check never fires. Use a non-blocking receive instead:

1
2
3
4
5
6
select {
case <-t.C:
	// fired
default:
	// not yet
}

The cleanup, in order

  1. Delete every godebug asynctimerchan=1 entry and //go:debug asynctimerchan=1 comment. Search go.mod and every .go file in the main module.
  2. Search for <-t.C directly after a Stop() or Reset() that is not guarded by the return value of Stop. Guard it, or delete it: since Go 1.23, Reset guarantees that no stale value can arrive afterwards, so the drain dance is no longer needed at all.
  3. Replace any len(t.C) polling with a select that has a default.
  4. If the go line is older than 1.23 and you relied on the old default, raise it deliberately, run the tests, and treat a hang in a timer path as the first suspect.

How to tell it worked

go build ./... and go vet ./... succeed on 1.27, and the small program above prints len before Stop: 0 and channel empty after Stop. For a real service the signal that matters is the absence of goroutines parked on a timer channel: take a goroutine profile under load and look for stacks sitting in a receive on t.C.

Sources

This post is licensed under CC BY 4.0 by the author.