Go: build constraints exclude all Go files in a package
The package vanished for this platform, not the code. Read the ignored file list, then rename a suffix or pass the tag.

Introduction & Quick Summary
go build fails with package github.com/acme/app/cmd/worker: build constraints exclude all Go files in /app/cmd/worker, or go test ./... skips a package that clearly contains tests. Nothing is wrong with the code: every file in that directory is excluded by its build constraints for the current platform, architecture, Go version or tag set.
The message is literal. The Go tool collected the files in the directory, evaluated each //go:build expression, and nothing survived. The usual reasons:
- A stale filename suffix.
worker_linux.gois only compiled on Linux;worker_amd64.goonly on amd64. A cross-compile todarwin/arm64excludes both, and if they were the only files, the package disappears. - A tag you did not pass.
//go:build integrationrequires-tags=integration; without it the file is invisible, and a package that consists of that one file reports the error. - A version constraint.
//go:build go1.24excludes the package when the local toolchain is older, which happens withGOTOOLCHAIN=localor a pinned CI image. - Contradictory expressions.
//go:build linux && !linuxcompiles nowhere; a&&that was meant to be||is the common slip.
The fixes are one of: pass the tag, build for the platform the files target, rename the suffix, or relax the expression. The first step is always to ask Go which files it considered and why it dropped them.
Core Mechanics, Signatures & Reproducible Setup
Go decides file membership before it parses anything. The rule set is: the filename must end in .go and not in _test.go for a normal build; the suffix before .go may encode GOOS, GOARCH and legacy tags; and a //go:build line near the top must evaluate true. There must be no blank line between the constraint comment and the package clause, and Go 1.17+ expressions supersede the older // +build lines, which still have to agree when both are present.
# which files, and why each is in or out
go list -f '{{.GoFiles}} {{.IgnoredGoFiles}}' ./cmd/worker
# [main.go] [worker_linux.go worker_amd64.go worker_integration.go]
# the platform and tags in effect
go env GOOS GOARCH GOVERSION CGO_ENABLED
go build -x -tags 'integration' ./cmd/worker 2>&1 | head -5A minimal reproduction makes the error and its resolution one command each:
mkdir -p demo/cmd/worker && cd demo && go mod init example.com/demo
cat > cmd/worker/worker_linux.go <<'EOF'
//go:build linux
package main
func main() {}
EOF
go build ./cmd/worker # ok on Linux
GOOS=darwin GOARCH=arm64 go build ./cmd/worker
# build constraints exclude all Go files in ...# the same package with a portable file
cat > cmd/worker/main.go <<'EOF'
package main
func main() {}
EOF
GOOS=darwin GOARCH=arm64 go build ./cmd/worker # okKey Comparison Table
| Mechanism | Example | Evaluated when | Notes |
|---|---|---|---|
| Filename suffix | worker_linux_amd64.go | before parsing | suffix must be the last element before .go |
| Build tag | //go:build integration | before parsing | needs -tags=integration |
| Negated tag | //go:build !windows | before parsing | default true on Linux and macOS |
| Version tag | //go:build go1.24 | before parsing | false on older toolchains |
| cgo | //go:build cgo | before parsing | false when CGO_ENABLED=0 |
| Ignored file | _ prefix or . prefix | always | never compiled, silently |
| Observation | Meaning | Next step |
|---|---|---|
| IgnoredGoFiles lists the only files | suffix or tag excluded them | build for that platform or pass the tag |
| IgnoredGoFiles empty, error remains | files are _name.go or in a subdirectory | check naming and package clause |
Works with -tags, fails without | tag-gated package | make one file unconditional |
| Fails only in Docker | different GOOS or Go version | print go env in both places |
| Fails only on Apple silicon | suffix targets amd64 | add arm64 files or drop the suffix |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. Suffix rules are stricter than people expect
The suffix is matched from the end, one element at a time, and an unknown element is just part of the name. worker_linux_arm.go is fine; worker_linux_v2.go is a file for all platforms; worker_linux_amd64_test.go is a test file for Linux amd64. When a name carries both a version and a platform, the last recognized pair wins:
go list -f '{{.Name}}: {{.GoFiles}} ignored: {{.IgnoredGoFiles}}' ./internal/workerIf a directory contains only platform files, the package does not exist for other platforms, and every importer fails with the same message, not just the build of that directory.
2. Tag-gated implementations need one portable file
The standard pattern is a default plus overrides. The default must be excluded on the platforms that have an override, or you get duplicate declarations:
//go:build !linux
package worker
func Platform() string { return "portable" }//go:build linux
package worker
func Platform() string { return "linux" }Without the !linux on the default, both files compile on Linux and the build fails with Platform redeclared in this block, which is a better error but a different one.
3. Integration and e2e tags
A package that holds only tag-gated tests looks broken to a plain go test ./..., and some CI systems treat "no Go files" as a hard failure. Two workable shapes:
# keep the package compilable without the tag
go test -tags=integration ./integration/...//go:build integration
package integrationAdd a doc.go in the same directory with no constraint so the package always exists; the test files stay gated and the package builds everywhere.
4. Cross-compilation in Docker
A golang:1.25-alpine builder and a node-style final image have different platform and cgo settings. Print the values that decide file membership inside the build, not on your laptop:
FROM golang:1.25-alpine AS build
RUN go env GOOS GOARCH CGO_ENABLED GOVERSION
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -o /out/app ./cmd/appWith CGO_ENABLED=0, every file marked //go:build cgo is excluded; if a package depends on one of them, the error names that package, not the value that caused it.
5. Version tags and toolchain downloads
//go:build go1.24 is false for a 1.23 toolchain. With GOTOOLCHAIN=local, Go will not download a newer one, and the package vanishes instead of reporting a version error:
go env GOTOOLCHAIN
GOTOOLCHAIN=go1.25.1 go build ./...For a library that supports several versions, gate on the feature rather than the release where possible, and keep one unconstrained file as the fallback implementation.
6. Confirming the final file set
Before hunting further, print the exact set the compiler will see for each target, then diff it against the working case:
for t in linux/amd64 linux/arm64 darwin/arm64 windows/amd64; do
GOOS=${t%/*} GOARCH=${t#*/} go list -f "$t {{.GoFiles}}" ./...
doneRun the same command in the container and on the host and compare the output in Text Diff; the platform whose file list loses an entry is the one whose constraint needs editing. For a tag expression you are editing by hand, keep a small table of the target matrix in the package comment so the next change does not reintroduce the exclusion.
Common Compilation/Runtime Mistakes & Version Gotchas
// +buildwithout a blank line beforepackage. The constraint is treated as documentation and ignored, which produces the opposite failure: the file compiles when it should not.- Blaming
go clean -cache. The error is deterministic and cache-independent; clearing it only costs time. - A
_test.gosuffix on a non-test file. It is silently excluded from the build and never reported as ignored. - A file starting with
_or.. Go ignores it without any notice, which is the one exclusion the tool cannot report. - Two
//go:buildlines. Only the first counts; the second is a comment. - Copying a build tag with the wrong operator.
linux,amd64(old syntax) means OR in+buildlines and AND in//go:build; mixing the two styles produces constraints that never agree. GOFLAGS=-tags=...set in one environment. A tag that is default locally and absent in CI moves files between the two builds without any diff.
Primary references: cmd/go build constraints documents the suffix rules and the expression grammar, and go.dev/cmd/go covers the same rules with the current release notes on the //go:build form.
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: cannot find main module and where go.mod is looked up
The go command searched upward and found no module. Create it at the right level, join modules with go.work, and check GOMOD before guessing.
Go: cgo: C compiler "gcc" not found in a minimal image
Why a project with no C fails on a C compiler, how to prove which package pulls cgo, and what changes when a library really needs it.
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.
Go: 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.