protoc "protoc-gen-go: program not found or is not executable" in CI

By Daniel Zoghalchali·Latchkey

protoc resolves a --go_out plugin by looking for an executable named protoc-gen-go on PATH. In CI the plugin was never installed, or it was installed under a GOPATH/bin directory that is not on PATH, so protoc cannot run it.

What this error means

protoc stops with "protoc-gen-go: program not found or is not executable" (and "Please specify a program using absolute path or make sure the program is available in your PATH"), exiting non-zero before any file is written.

protoc-gen-go: program not found or is not executable
Please specify a program using absolute path or make sure the program is available in your PATH system variable
--go_out: protoc-gen-go: Plugin failed with status code 1.

Common causes

The plugin binary was never installed on the runner

protoc itself is present but protoc-gen-go is a separate Go program that must be installed with go install. A fresh runner has neither it nor the gRPC plugin.

The plugin is installed but GOPATH/bin is not on PATH

go install drops the binary in $(go env GOPATH)/bin (or $(go env GOBIN)). If that directory is not added to PATH, protoc cannot discover the plugin.

How to fix it

Install the plugin and put GOPATH/bin on PATH

1. Install protoc-gen-go (and protoc-gen-go-grpc if you generate gRPC) with go install.
2. Add $(go env GOPATH)/bin to the PATH for later steps.
3. Re-run protoc so it can resolve the --go_out plugin.

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

Point protoc at the plugin explicitly

If you cannot change PATH, pass the absolute plugin path so protoc does not rely on a lookup.

protoc --plugin=protoc-gen-go="$(go env GOPATH)/bin/protoc-gen-go" \
  --go_out=. api/service.proto

How to prevent it

• Install codegen plugins in a dedicated setup step before generation.
• Append $(go env GOPATH)/bin to GITHUB_PATH so every later step sees it.
• Pin plugin versions (@v1.34.2) so generated output is reproducible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation