Skip to content

Troubleshooting code generation#

Common errors and unexpected results from buf generate, with fixes. If the error isn’t listed here, check the code generation overview and the buf.gen.yaml reference, or open a Buf issue.

C#: “file … was generated multiple times”#

C# plugins emit one file per class but won’t lay them out in a directory hierarchy unless you tell the plugin which namespace prefix to strip. Set base_namespace as a plugin option:

version: v2
managed:
  enabled: true
plugins:
  - remote: buf.build/protocolbuffers/csharp
    out: gen/proto/csharp
    opt: base_namespace=NAMESPACE

base_namespace is a plugin option, separate from the csharp_namespace file option that managed mode controls.

Python: ModuleNotFoundError on a generated module#

If buf generate produces Python files but importing them raises ModuleNotFoundError: No module named 'buf…', add an empty __init__.py to the root of the generated output.

This is a long-standing Protobuf issue; see the recommended workaround for context.

PHP gRPC: service interfaces aren’t generated#

The Buf CLI doesn’t produce PHP gRPC service interface classes, even when older protoc versions did. The php_generic_services file option that controlled interface generation was removed from Protobuf, and the Buf CLI tracks current Protobuf releases. There’s no Buf-side workaround.

Import paths don’t resolve when running buf generate#

buf generate reports it can’t find a file referenced in an import statement.

The cause is usually a mismatch between the input argument and the path inside the import. By default, buf generate uses the workspace root (the directory containing buf.yaml) as the resolution root. With this layout:

.
├── buf.gen.yaml
├── buf.yaml
└── proto
    ├── foo
    │   └── foo.proto
    └── bar
        └── bar.proto

Running buf generate from the workspace root resolves import paths relative to that root:

proto/bar/bar.proto
import "proto/foo/foo.proto";

Passing an explicit input changes the resolution root to that input. buf generate proto resolves proto/foo/foo.proto as proto/proto/foo/foo.proto, which doesn’t exist. With proto/ as the input, the import should be:

proto/bar/bar.proto
import "foo/foo.proto";

“Unknown type” errors across packages#

If imports resolve but the compiler reports an unknown type, the cause is usually a missing package qualifier on the type reference. Protobuf requires fully-qualified names when referring to a type defined in another package.

For the layout above, if foo.proto declares package proto.foo; and bar.proto declares package proto.bar;, referring to Foo from bar.proto requires the package prefix:

proto/bar/bar.proto
syntax = "proto3";

package proto.bar;

import "proto/foo/foo.proto";

message Bar {
  proto.foo.Foo my_foo = 1;
}

This isn’t Buf-specific; it’s general Protobuf semantics.