Buf Schema Registry 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%\buf on 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:

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:

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 branch?

You can't. The BSR is not just a VCS, but also a package registry (because of generated SDKs), so deleting a branch can have side effects that are much more impactful than branch deletion in Git.

Is there a way to easily diff schema branches?

In your repository on the BSR, go to the Activity tab. From this tab, you can compare commits, branches, and tags 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

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

Generating code

How can I modify the output of generated SDKs and/or change the plugin options?

There is currently no way to modify the generated SDK output directly. We have an opinionated set of plugin options (usually the defaults) which determine the output. Your choices are:

• Local code generation
• Remote plugin code generation
• For Pro or Enterprise plans, you can upload a custom plugin and specify the desired plugin options to be used during code generation.

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 except field:

version: v1
managed:
  enabled: true
  go_package_prefix:
    default: github.com/<org>/<repo> # Local path
    except: buf.build/googleapis/googleapis
plugins:
  - plugin: go
    out: gen
    opt: paths=source_relative
  - name: go-grpc
    out: gen
    opt: paths=source_relative