Go "package command-line-arguments is not a main package" - Fix in CI

By Kaveh Alemi·Latchkey

When you pass file paths to go build or go run, Go groups them into a synthetic command-line-arguments package. If those files are not package main, it cannot produce an executable.

What this error means

A build or run fails with package command-line-arguments is not a main package. It usually means CI passed individual .go files (or a non-main file set) to go build/run instead of a package path.

go run util.go
package command-line-arguments is not a main package

Diagnose it: toolchain, tags, or platform?

Go build failures that only appear in CI usually come from a different toolchain version, different build tags, or cross-compilation defaults that differ from your machine.

go version
go env GOOS GOARCH CGO_ENABLED GOFLAGS GOTOOLCHAIN

# build exactly what CI builds, verbosely
go build -v ./... 2>&1 | tail -40

# CGO is the usual difference: on by default locally, often off in a slim CI image
CGO_ENABLED=0 go build ./...

Common causes

Built loose files instead of a package

Passing specific .go files makes Go treat them as command-line-arguments, which must be main to build a binary.

The named files are not package main

The files belong to a library package, so there is no func main to build.

How to fix it

Build the package path, not files

1. Point go build/run at the package directory containing func main.

go run ./cmd/app
go build ./cmd/app

Pass the full main file set

1. If you must name files, include every file of the main package, not a subset.

go run main.go util.go

How to prevent it

• Build package paths (./cmd/app) rather than individual files.
• Keep func main in the package you intend to run.
• Avoid passing partial file lists to go build/run.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation