buf remote plugin "not found" in CI

By Kaveh Alemi·Latchkey

buf resolves each remote: plugin against the registry at run time. A "not found" means the exact name or version does not exist (a typo or a yanked version), or the runner could not reach the registry over the network.

What this error means

buf generate fails resolving a remote plugin, for example "plugin buf.build/protocolbuffers/go:v9.9.9 does not exist" or a network error contacting the registry.

Failure: plugin "buf.build/protocolbuffers/go:v9.9.9" was not found
Error: Process completed with exit code 1.

Common causes

A wrong plugin name or version

The referenced remote plugin path or version tag does not exist on the registry, so resolution fails deterministically.

The registry is unreachable from the runner

A network block or transient outage prevents buf from fetching the remote plugin.

How to fix it

Reference an existing plugin and version

1. Confirm the plugin path and a published version on buf.build.
2. Update buf.gen.yaml to a real name and version.
3. Re-run buf generate.

version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.34.2
    out: gen

Retry on a transient network failure

If the reference is valid, a resolution failure is usually a transient network drop; re-running the job clears it.

How to prevent it

• Pin remote plugins to versions verified to exist on the registry.
• Review plugin references when upgrading generated code.
• Retry transient registry-network failures automatically.

Frequently asked questions

Related guides

References

• GitHub Actions documentation