Go "protoc-gen-go: program not found" - Fix in CI

By Kaveh Alemi·Latchkey

protoc finds its plugins by looking for protoc-gen-<name> on PATH. When protoc-gen-go was never installed, or GOBIN is not on PATH, protoc cannot launch the Go generator.

What this error means

A protobuf codegen step fails with protoc-gen-go: program not found or is not executable. The plugin binary is missing from PATH in the runner.

protoc-gen-go: program not found or is not executable
--go_out: protoc-gen-go: Plugin failed with status code 1.

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

Plugin not installed

protoc-gen-go was never go installed in the runner, so protoc cannot find it.

GOBIN not on PATH

The plugin installed into GOPATH/bin but that directory is not on PATH.

How to fix it

Install the plugin and export PATH

1. go install the Go and gRPC plugins.
2. Add the Go bin directory to PATH so protoc can find them.

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"

Pin the plugin version

1. Pin protoc-gen-go in a tools file so generated code is reproducible.

import _ "google.golang.org/protobuf/cmd/protoc-gen-go"

How to prevent it

• Install codegen plugins in CI before running protoc.
• Add $(go env GOPATH)/bin to GITHUB_PATH.
• Pin plugin versions in a tools file for reproducible output.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation