Cross-Version Runtime Guarantee

Protobuf language bindings have two components. The generated code (typically produced from protoc) and the runtime libraries that must be included when using the generated code. When these come from different releases of protobuf, we are in a “cross version runtime” situation.

We intend to offer the following guarantees across all languages except C++. These are the default guarantees; however, owners of protobuf code generators and runtimes may explicitly override them with more specific guarantees for that language.

Protobuf cross-version usages outside the guarantees are error-prone and not supported. Version skews can lead to flakes and undefined behaviors that are hard to diagnose, even if it can often seem to work as long as nothing has changed in a source-incompatible way. For Protobuf, the proliferation of tools and services that rely on using unsupported Protobuf language bindings prevents the protobuf team from updating the protobuf implementation in response to bug reports or security vulnerabilities.

New Gencode + Old Runtime = Never Allowed

We may add new runtime APIs in any kind of release (Major, Minor, or Patch). Gencode in that release is allowed to use those new APIs. The consequence is that gencode should never be paired with a runtime that predates the protoc and plugin that was used to generate those bindings.

We will add “poison pills” where possible to prevent attempts to pair newer gencode with an older runtime.

Major Versions

Starting with the 2025Q1 release, the protobuf project will adopt a rolling compatibility window for major versions. Code generated for a major version V (full version: V.x.y) will be supported by protobuf runtimes of version V and V+1.

Prior to this policy, code generated for 3.22.x+ (release ~1 year prior to major version 4) will still be supported by protobuf runtimes of version 3 and 4. Users with older gencode should upgrade to the latest gencode from 3.25.x.

Protobuf will not support using gencode from version V with runtime >= V+2 and will be using a “poison pill” mechanism to fail with a clear error message when a software assembly attempts to use such a configuration.

Minor Versions

Within a single major runtime version, generated code from an older version of protoc will run on a newer runtime.

Security Exception

We reserve the right to violate the above promises if needed for security reasons. We expect these exceptions to be rare, but will always prioritize security above these guarantees. For example, footmitten required paired updates to both the runtime and the generated code for Java. As a result, code generated by 3.20.3 (which contained the footmitten fix) would not load with runtime library 3.21.6 (which predates the footmitten fix), creating the following compatibility matrix:

• “Vuln” indicates that the combination will successfully start, but the security vulnerability still exists.
• “Works” indicates that the combination will successfully start and does not have the vulnerability.
• “Broken” indicates that the combination will not successfully start.
• Bold indicates configurations that were never deliberately intended to function together given the guarantees outlined in this topic.

No Coexistence of Multiple Major Runtime Versions

Coexistence of multiple major versions in the same process is not supported.

C++ Specific Guarantees

Protobuf C++ disclaims all cross-runtime support and requires an exact match between its generated code version and its runtime version at all times. Additionally, Protobuf C++ makes no guarantees about ABI stability across any releases (major, minor, or micro).