cmd/go: better document GODEBUG defaults and behavior in GOPATH mode

[rittneje]

Go version

go version go1.24.3 darwin/amd64

Output of go env in your module/workspace:

AR='ar'
CC='clang'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='clang++'
GCCGO='gccgo'
GO111MODULE='auto'
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/tmp/.gocache'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/rittneje/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch x86_64 -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/kf/kr7_s3xx0l12zbj3jrn082hmzy5gvy/T/go-build2339782732=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='amd64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD=''
GOMODCACHE='/Users/rittneje/go/pkg/mod'
GONOPROXY='[REDACTED]'
GONOSUMDB='[REDACTED]'
GOOS='darwin'
GOPATH='/Users/rittneje/go'
GOPRIVATE='[REDACTED]'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/Users/rittneje/go1.24.3'
GOSUMDB='sum.golang.org'
GOTELEMETRY='off'
GOTELEMETRYDIR='/Users/rittneje/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='local'
GOTOOLDIR='/Users/rittneje/go1.24.3/pkg/tool/darwin_amd64'
GOVCS='[REDACTED]'
GOVERSION='go1.24.3'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

Consider the following program.

main.go

package main

import (
	"fmt"
	"runtime/debug"
)

func main() {
	bi, ok := debug.ReadBuildInfo()
	if !ok {
		panic("could not read build info")
	}
	for _, s := range bi.Settings {
		if s.Key == "DefaultGODEBUG" {
			fmt.Println(s.Value)
		}
	}
}

go.mod

module godebugtest

godebug default=go1.20

go 1.24.3

What did you see happen?

If I build this application in GOPATH mode, it prints:

asynctimerchan=1,gotestjsonbuildtext=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,multipathtcp=0,netedns0=0,panicnil=1,randseednop=0,rsa1024min=0,tls10server=1,tls3des=1,tlsmlkem=0,tlsrsakex=1,tlsunsafeekm=1,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1,x509rsacrt=0,x509usepolicies=0

However, if I build this application in go mod mode, it prints:

asynctimerchan=1,gotestjsonbuildtext=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,multipathtcp=0,panicnil=1,randseednop=0,rsa1024min=0,tls10server=1,tls3des=1,tlsmlkem=0,tlsrsakex=1,tlsunsafeekm=1,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1,x509rsacrt=0,x509usepolicies=0

As you can see, they differ only in the value/presence of netedns0.

What did you expect to see?

From what I can tell, it is not documented anywhere what GOPATH mode is supposed to do for DefaultGODEBUG.

My guess is that GOPATH mode is supposed to be the same as godebug default=go1.20 given that they report almost identical values for DefaultGODEBUG, in which they should agree on the value of netedns0. And the fact that GOPATH mode means godebug default=go1.20 should be mentioned on https://go.dev/doc/godebug.

[seankhliao]

I don't see why it follows that it should default to go1.20.
In fact right now it defaults to go1.18, which is before any godebug defaults were changed.

[rittneje]

@seankhliao That seems to contradict both what you have said previously and the experimental evidence.

[thepudds]

I suspect netedns0 is different because it has Changed: 19 specified:

go/src/internal/godebugs/table.go

Line 57 in 1555fad

{Name: "netedns0", Package: "net", Changed: 19, Old: "0"},

(I had looked at this very briefly and started a reply ~6 months ago that I think is lost to some closed browser tab; my conclusion at the time was that on the question of whether GODEBUGs should float forward or float back in GOPATH mode, it seemed there were some contradictory statements in different issues / CLs, so it seemed plausible to me ~6 months ago that it might not have been an extensively discussed decision.)

---

Separately, one option that I've never tried myself is:

If you want to target Go 1.22, you put this line above the package main in the example above:

//go:debug default=go1.22

via @siebenmann and https://www.tuxed.net/fkooman/blog/go-without-modules.html.

---

I do think it would be good to document the behavior for GODEBUGs in GOPATH mode a little better, ideally after some level of agreement on what the behavior should be.

[thepudds]

@matloob in #71412 (comment) wrote:

This is working as intended. The default 1.20 value can be overridden using the GODEBUG environment variable.

I am going to take the liberty of changing this issue here to a documentation issue.

(The original report related to netedns0 I'm guessing is related to what I said in my immediately prior comment.)

[rittneje]

@thepudds The comment you linked directly contradicts what is observed here. It implies that GOPATH mode is supposed to mean GODEBUG=default=go1.20. Hence, this is still a bug.

[thepudds]

Hi @rittneje, without really having done much investigation here, I suspect it's just using the oldest known GODEBUG values in GOPATH mode.

Does that align with your observations, vs. maybe do you have a counter example?

For many GODEBUGs, that might happen to be a Go 1.20 value, but I suspect netedns0 is different because it has Changed: 19 specified in that table I linked to a couple of comments back. (It's the only entry in the table with Changed: 19 or earlier, based on taking on a quick look, but maybe if you take a closer look you'll come to a different conclusion.)

Also, to be clear, I don't personally have any problem I'm trying to solve here. I'm just an external contributor trying to help move this issue forward.

I also suspect there is probably not enormous appetite for changing the behavior, especially if there is concern someone might then complain about a change in behavior when Go 1.27 or Go 1.2x is released.

[thepudds]

I guess I'll add that I believe it is intentionally a different answer for the Go language version used in GOPATH mode compared to the default GODEBUG settings when in GOPATH mode.

For example, in #70641 (comment), I believe this comment is about the Go language version in GOPATH mode (which empirically is clearly different behavior than the default GODEBUGs in GOPATH mode):

This was previously reported as #65612 in the command-line-arguments context, but it's the same underlying issue for GOPATH. We fixed this in 1.23 with https://go.dev/cl/593156, explicitly setting the go version to the toolchain version when outside of a module.