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 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
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
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:
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-import
s flag to buf generate
. Alternatively, you can specify include_imports: true
per plugin in your buf.gen.yaml
file.