buf module "not found" on the Buf Schema Registry in CI

By Kaveh Alemi·Latchkey

buf could not resolve a module reference on the registry. Either the owner/module path is wrong, or the module is private and the request was unauthenticated or made with a token lacking read access.

What this error means

buf fails with "Failure: module buf.build/acme/petapis does not exist" or a 404/403 when resolving a dependency or a breaking-change baseline from the BSR.

Failure: module "buf.build/acme/petapis" does not exist or you do not have
access to it.

Common causes

A wrong owner or module name

A typo in the buf.build path means the registry has no such module, returning not found.

A private module without valid credentials

A private module needs a BUF_TOKEN with read access; without it the registry hides the module and reports it as not found.

How to fix it

Fix the module reference

1. Verify the exact buf.build/<owner>/<module> path.
2. Correct any typo in buf.yaml deps or the --against target.
3. Re-run the command.

version: v2
deps:
  - buf.build/acme/paymentapis

Authenticate for a private module

Pass a BUF_TOKEN with read access so the registry resolves the private module.

- uses: bufbuild/buf-setup-action@v1
  with:
    buf_token: ${{ secrets.BUF_TOKEN }}

How to prevent it

• Reference modules by their exact registry path.
• Provide a read-scoped BUF_TOKEN for private modules.
• Pin dependency modules in buf.lock so references stay stable.

Frequently asked questions

Related guides

References

• GitHub Actions documentation