cmd/go: confusing situation with 'go run' and '//go:build ignore'

[josharian]

Go version

go version go1.24.2 darwin/arm64

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=''
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN='/Users/josh/bin'
GOCACHE='/Users/josh/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/josh/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/vm/htvrhp4177v2dfhdjlvl0pqh0000gn/T/go-build275806226=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD=[redacted]
GOMODCACHE='/Users/josh/pkg/mod'
GONOPROXY=[redacted]
GONOSUMDB=[redacted]
GOOS='darwin'
GOPATH='/Users/josh'
GOPRIVATE=[redacted]
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/Users/josh/pkg/mod/golang.org/toolchain@v0.0.1-go1.24.2.darwin-arm64'
GOSUMDB='sum.golang.org'
GOTELEMETRY='on'
GOTELEMETRYDIR='/Users/josh/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/Users/josh/pkg/mod/golang.org/toolchain@v0.0.1-go1.24.2.darwin-arm64/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.24.2'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

Here's my terminal transcript:

$ go run x.go
go: updates to go.mod needed; to update it:
	go mod tidy
$ go mod tidy
$ go run x.go
go: updates to go.mod needed; to update it:
	go mod tidy
$ go mod tidy
$ go run x.go
go: updates to go.mod needed; to update it:
	go mod tidy

After quite a while spend debugging, it turns out the problem is that x.go had //go:build ignore, and so go mod tidy ignored it...leaving it in a broken state when actually running it.

Even once I had a diagnosis, it was non-trivial to work around, because go mod tidy has no place to specify build tags. I had to move the file to a new location, remove the build tag, run go mod tidy, and then put it all back together again.

What did you see happen?

covered above.

What did you expect to see?

again, covered above.

[seankhliao]

Related #54993

[seankhliao]

you could have run go run -mod=mod x.go

[josharian]

you could have run go run -mod=mod x.go

certainly having that in the error message would have helped

[seankhliao]

taking a step back though, would it have been better for your script to be tracked as a tool package (and have its dependencies tracked)?
perhaps we should more strongly discourage the use of go run file.go.

[gabyhelp]

Related Issues

• x/build: Strange behavior with a particular file name #69722 (closed)
• cmd/go: run constantly fails and suggests 'go mod tidy' #41416 (closed)
• cmd/go: go run cannot build a command in a module directory #33890 (closed)
• cmd/go: error out in 'go mod tidy' if the result uses a module for multiple paths #34650 (closed)
• cmd/go: build failed #59694 (closed)
• cmd/go: build constraint of 'ignore' is special for modules? #29598 (closed)
• compiler detects module based on current working directory #68043 (closed)
• cmd/go/internal/script: fix build tags of isETXTBSY #67356 (closed)
• Suddenly go build doesn't respect '// +build ignore' flag #28687 (closed)
• cmd/go: improve build list errors related to replace and exclude directives #35039 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[josharian]

taking a step back though, would it have been better for your script to be tracked as a tool package (and have its dependencies tracked)?

i don't think so, no.

perhaps we should more strongly discourage the use of go run file.go.

it's really, really useful to be able to have little scripts.

[thepudds]

Hi @josharian, improving the error here would likely be helpful.

One question though regarding your use of //go:build ignore in the x.go file. Do you:

1. want the imports in x.go to not "pollute" the results of a normal go mod tidy (and maybe that's why you are using //go:build ignore), or
2. want the imports in x.go in general to influence what's in your go.mod, but you just don't want something like go build to build x.go, or
3. maybe want something else?

For your particular case, would it have helped if x.go instead had //go:build run (or some other build tag instead of //go:build ignore)?

It sounds like you are well aware of the underlying mechanisms, but at least for my reference, from the go mod tidy doc:

go mod tidy acts as if all build tags are enabled, so it will consider platform-specific source files and files that require custom build tags, even if those source files wouldn’t normally be built. There is one exception: the ignore build tag is not enabled, so a file with the build constraint // +build ignore will not be considered.

and from the go run doc:

Typically the package is specified as a list of .go source files from a single directory, but it may also be an import path, file system path, or pattern matching a single known package [...]

If the package argument doesn't have a version suffix, "go run" may run in module-aware mode or GOPATH mode, depending on the GO111MODULE environment variable and the presence of a go.mod file. [...] If module-aware mode is enabled, "go run" runs in the context of the main module.

[josharian]

Thanks.

The use of //go:build ignore is because (a) the "natural" place for this script is amongst the other files in that directory and (b) using //go:build ignore makes gopls usable with the script. IIRC, but maybe I'm wrong, using something other than ignore as the build tag doesn't help with gopls.

I'm genuinely unsure about what the right fix is here.

[thepudds]

For gopls, it looks like you could add a run build tag (or whatever) to the standaloneTags setting, which otherwise defaults to ignore:

https://github.com/golang/tools/blob/master/gopls/doc/settings.md#standalonetags-string

standaloneTags specifies a set of build constraints that identify individual Go source files that make up the entire main package of an executable.

A common example of standalone main files is the convention of using the directive //go:build ignore to denote files that are not intended to be included in any package, for example because they are invoked directly by the developer using go run.

Gopls considers a file to be a standalone main file if and only if it has package name "main" and has a build directive of the exact form "//go:build tag" or "// +build tag", where tag is among the list of tags configured by this setting. Notably, if the build constraint is more complicated than a simple tag (such as the composite constraint //go:build tag && go1.18), the file is not considered to be a standalone main file.

Default: ["ignore"].

[josharian]

Good to know, thanks!

Definitely feels a bit like the defaults are fighting with each other here. :P

[thepudds]

Perhaps some new build tag convention could be established for standalone main files, and then the default gopls setting could use that convention in addition to ignore, though maybe that is not desirable (and is not an immediate fix, and would take some discussion, etc.).

That said, I guess I'm curious what was out of sync in your particular example.

In at least some common cases, it does seem to give a better error. For example, if I have a package main file with a //go:build ignore and it has an import that is not covered by the require directives in the current module's go.mod, and I try to run that file, I get an error like:

$ go run t.go
t.go:8:2: no required module provides package rsc.io/quote; to add it:
        go get rsc.io/quote

From a quick look at the cmd/go code, the error you saw can happen when it thinks the go.mod is dirty in another way. For example, if I edit a version in my go.mod to no longer be in canonical form (e.g., require golang.org/x/text 14c0d48ead0c), I can get:

$ go run t.go
go: updates to go.mod needed; to update it:
        go mod tidy

That's probably not exactly what you hit, though, and while I could probably trigger that specific error in other ways, I'm curious what was out of sync for you in particular (if that was apparent based on your debugging).

[josharian]

It was missing some imports. Not sure why it differed from your experiments.