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

By Kaveh Alemi·Latchkey

protoc found a --go_out plugin request but could not locate the protoc-gen-go executable on PATH. protoc discovers plugins by name from PATH, so the Go plugin binary must be installed and its install directory exported.

What this error means

protoc fails 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."

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.
--go_out: protoc-gen-go: Plugin failed with status code 1.

Common causes

The plugin was never installed

protoc-gen-go is a separate Go binary; without go install google.golang.org/protobuf/cmd/protoc-gen-go, protoc cannot invoke --go_out.

GOBIN / GOPATH bin is not on PATH

go install places the binary in $(go env GOPATH)/bin, which is not on PATH by default on the runner, so protoc cannot find it.

How to fix it

Install the plugin and add GOPATH/bin to PATH

1. Install protoc-gen-go with a pinned version.
2. Append $(go env GOPATH)/bin to GITHUB_PATH.
3. Re-run protoc so it discovers the plugin.

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

Point protoc at the plugin explicitly

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

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

How to prevent it

• Install codegen plugins with pinned versions in a setup step.
• Export $(go env GOPATH)/bin to PATH before running protoc.
• Prefer buf generate with remote plugins to avoid PATH setup entirely.

Frequently asked questions

Related guides

References

• GitHub Actions documentation