Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readGo
#Go#Build Tags#Cross Compilation#Tooling
A package folder whose file slabs are all rejected by amber constraint tags at a cyan gate

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:

  1. A stale filename suffix. worker_linux.go is only compiled on Linux; worker_amd64.go only on amd64. A cross-compile to darwin/arm64 excludes both, and if they were the only files, the package disappears.
  2. A tag you did not pass. //go:build integration requires -tags=integration; without it the file is invisible, and a package that consists of that one file reports the error.
  3. A version constraint. //go:build go1.24 excludes the package when the local toolchain is older, which happens with GOTOOLCHAIN=local or a pinned CI image.
  4. Contradictory expressions. //go:build linux && !linux compiles 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.

bash
# 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 -5

A minimal reproduction makes the error and its resolution one command each:

bash
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 ...
bash
# 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 # ok

Key Comparison Table

MechanismExampleEvaluated whenNotes
Filename suffixworker_linux_amd64.gobefore parsingsuffix must be the last element before .go
Build tag//go:build integrationbefore parsingneeds -tags=integration
Negated tag//go:build !windowsbefore parsingdefault true on Linux and macOS
Version tag//go:build go1.24before parsingfalse on older toolchains
cgo//go:build cgobefore parsingfalse when CGO_ENABLED=0
Ignored file_ prefix or . prefixalwaysnever compiled, silently
ObservationMeaningNext step
IgnoredGoFiles lists the only filessuffix or tag excluded thembuild for that platform or pass the tag
IgnoredGoFiles empty, error remainsfiles are _name.go or in a subdirectorycheck naming and package clause
Works with -tags, fails withouttag-gated packagemake one file unconditional
Fails only in Dockerdifferent GOOS or Go versionprint go env in both places
Fails only on Apple siliconsuffix targets amd64add 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:

bash
go list -f '{{.Name}}: {{.GoFiles}} ignored: {{.IgnoredGoFiles}}' ./internal/worker

If 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
//go:build !linux package worker func Platform() string { return "portable" }
go
//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:

bash
# keep the package compilable without the tag go test -tags=integration ./integration/...
go
//go:build integration package integration

Add 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:

dockerfile
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/app

With 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:

bash
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:

bash
for t in linux/amd64 linux/arm64 darwin/arm64 windows/amd64; do GOOS=${t%/*} GOARCH=${t#*/} go list -f "$t {{.GoFiles}}" ./... done

Run 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

  • // +build without a blank line before package. 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.go suffix 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:build lines. Only the first counts; the second is a comment.
  • Copying a build tag with the wrong operator. linux,amd64 (old syntax) means OR in +build lines 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 documentation

The Go documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Go guides