Skip to content

Buf Schema Registry (BSR) FAQs

Can I depend on modules from the BSR and use the Buf CLI when offline?

Yes. Buf caches your dependencies locally when you run commands that use them (such as buf build, buf lint, and buf breaking) while connected to the Internet. By default, your cache lives at ~/.cache/buf on Mac or Linux, and %LocalAppData%\bufon Windows. All commands that use module dependencies will continue to work once your cache is initially populated.

Can I use remote plugins when offline?

No. protoc plugins are built and executed in a number of ways across the Protobuf ecosystem: compiled executables (statically or dynamically linked), JVM JAR files, files run with NPM, and so on. We use Docker to package protoc plugins and make them available for universal use, and this ability to specify a single value in your buf.gen.yaml file without needing to know how the plugin is developed is a key reason remote plugins are so valuable.

However, we don't think it's a good idea for the Buf CLI to require you to have a working Docker installation locally—it would negate much of the universal benefit of Buf itself. So, we engineered remote plugins to run on our servers. We copy your .proto files to the BSR, then run a Docker container there to execute the plugin and send back the generated code. This means that remote plugins require you to be connected to the BSR.

We've started working on a WASM-based protoc plugin ecosystem that would solve this issue, where we'd provide you with a WASM binary that you'd download and execute locally. This is the best future we can see for offline use. However, WASM is still in relative infancy, and we want to get more buy-in across the Protobuf community before enabling a WASM-based plugin ecosystem more widely.

Does a deps value in my buf.yaml file have to be a reference to a BSR module?

Yes. The value must be a valid path to a BSR module (either the public BSR at buf.build or a private BSR instance). It can't be a local Git reference to a buf.yaml file or a URL path to a Git repo. This means that if you have a module that you'd like to use as a dependency, it must also be pushed to the BSR.

How do I use Well Known Types from the google.protobuf package?

As the name implies, Well Known Types are known to the runtime, and in most cases already have generated code in the proto runtime. These files can be imported without declaring any dependency and without having copies of these files in your module. See the standard imports for a full list and more details.

Where can I find available options for a plugin on the BSR?

On the left-hand sidebar of the plugin page, there's a link to the plugin's GitHub repository, where details like plugin options, tutorials, and documentation should be available:

Screenshot of 'About' section of plugin page

If you're using a plugin as part of a generated SDK for one of your modules, the SDKs tab of your module also has a link to the integration guide for the plugin:

Screenshot of integration guide link

How do I document my Protobuf schema?

Protobuf supports comments, and we encourage you to document your Protobuf types and services like you document other code. The BSR auto-generates documentation for your Protobuf schema.

How do I delete a label?

You can't. Because the BSR is a package registry (because of generated SDKs), deleting a label can have side effects that are much more impactful than branch deletion in Git. However, you can archive a label.

Is there a way to easily diff schemas?

In your repository on the BSR, go to the Commits tab. From this tab, you can compare any two commits within a given label against each other.

What should I do if a user's credentials are compromised?

In the public BSR at buf.build, remove the user from your organization (if they're in your organization):

https://buf.build/<YOUR_ORG>/members

If you're on a private BSR server, also delete the user with the Deactivate button here:

https://<PRIVATE_BSR_SERVER>/admin/users

Note

We recommend using bot users for all automation tasks.

I pushed up a change to the BSR for my module—why don't I see a new version generated for my Go SDKs?

The public Go module proxy (and the docs) can take ~30 min to update. From their docs:

it may take up to 30 minutes for the mirror's cache to expire and fresh data about the version to become available.

This can also be true when you buf push and immediately do a go get ...@latest. In this case, it won't pick up the latest commit for a bit because the go env GOPROXY for most folks is https://proxy.golang.org,direct. To overcome this, you can fetch directly from the BSR Go module proxy and bypass the Google module proxy:

GOPRIVATE=buf.build/gen/go go get ... @latest

Is it OK to proxy the official BSR without additional credentials?

Yes—credentials are optional for public modules in the public BSR. You can give it a try here: https://buf.build/connectrpc/eliza/sdks/main

Generating code

How can I configure generated SDKs (like use different plugin options)?

For Free and Teams plans,you can't configure plugin options for generated SDKs. Instead, you can use the Buf CLI to generate the files yourself, and provide whatever configuration you want:

For Pro and Enterprise plans, you can upload a custom plugin that's the same as the plugin you are trying to use but with modifications in the registry stanza of the buf.plugin.yaml file. If you're modifying one of the default/curated plugins, you can get their configuration from GitHub.

Why does generating Java code using my valid module as an input result in an error?

Some users' Protobuf packages may use Java reserved keywords (public, native, etc.). The generated code will fail to compile if it includes one of these keywords, regardless of whether it is generated by a plugin locally or remotely. We suggest avoiding the use of Java reserved keywords in modules that you expect to use for generating code.

Can Maven JARs be hosted without the build.buf.gen prefix?

No. The package name prefix is tied to the host name of the BSR, so it can't be changed or removed. Private BSR instances for Pro, Enterprise, and On-prem plans have a different prefix based on their host name, however.

When I run buf generate, my Go code has incorrect imports for dependencies. How do I fix this?

This is often due to the use of managed mode, which overwrites Go import paths using the configuration in buf.gen.yaml. If you don't want to use the managed configuration for some dependencies, you must add an except entry in buf.gen.yaml under the managed.go_package_prefix stanza.

When I use a generated Go SDK, the Go code is using the wrong import for dependencies. How do I fix this?

Use of generated SDKs requires that all of the module's imports also use generated SDKs. This cannot be changed or configured. If you really need your module to import Go code from some other Go import path, you need to generate your own SDKs with relevant configuration.

Is there any way to configure the go_package behavior for Go generated SDKs?

No. The go_package option is automatically set to match the module name and package path so that you don't need to set it at all.

Why are googleapis imported from the local import path instead of the BSR?

This can happen if you're using managed mode to set the default for the go_package_prefix. To mitigate this, add buf.build/googleapis/googleapis to the disable field:

buf.gen.yaml
version: v2
managed:
  enabled: true
  override:
    - file_option: go_package_prefix
      value: github.com/<org>/<repo> # Local path
  disable:
    - file_option: go_package_prefix
      module: buf.build/googleapis/googleapis
plugins:
  - local: go
    out: gen
    opt: paths=source_relative
  - local: go-grpc
    out: gen
    opt: paths=source_relative

I get a 422 status code when trying to install a Python generated SDK. How do I get more information about what went wrong?

A 422 status code means that the plugin failed to run. You can curl the wheel endpoint (which pip provides in the error message as a URL ending in .whl) or open it in your browser to get more details about the failure.

How do I get pkg.go.dev to render a Buf-generated package?

You need to have a LICENSE file (or at least a symlink to one) in your module directory for it to get put as part of your Go module, per the Go license policy.

I have buf.build/googleapis/googleapis in my dependencies—why isn't it generated?

To generate your module and imports from dependencies, pass the --include-imports flag to buf generate. Alternatively, you can specify include_imports: true per plugin in your buf.gen.yaml file.

Why do I get a 404 error when trying to install the generated Go SDK for buf.build/googleapis/googleapis?

All types in googleapis/googleapis have a go_package option that points to the canonical package: google.golang.org/genproto/googleapis. We recommend that you import the canonical packages, and that you don't generate googleapis yourself.

How do I configure buf generate to only output one service, but still be aware of other definitions in the same Protobuf file root?

Use the --type flag. If you have the service BarService in package foo.v1, use --type foo.v1.BarService to generate only this service and the messages and enumerations it requires. You can also specify type filters in your buf.gen.yaml file by listing the types as part of an inputs declaration:

version: v2
inputs:
  - directory: ./path/to/proto_root
    types:
      - company.shared.v1.SomeService

See the code generation overview for more details.