C++20 Modules: GCC 13 BMIs Rejected After Toolchain Upgrade to GCC 14

Question

Module builds break at the compiler boundary

A project uses named C++20 modules and compiles cleanly on developer machines running GCC 13. After the production toolchain moves to GCC 14, importing those same modules fails with BMI version mismatch errors, even though no source code changed.

From what I understand, the C++ standard deliberately leaves the Binary Module Interface format unspecified, so BMIs are compiler-specific build artifacts rather than portable outputs. That raises a design question for projects that want to cache or distribute compiled modules across environments.

Constraints

Developer machines and CI/production runners may not always share identical compiler versions, including patch level.
Some translation units still use traditional headers, so modules and non-module code are mixed in one binary.
Prebuilt BMIs would speed up CI, but only if they remain valid across environments.

Open questions

Is exact compiler version parity (down to patch release) a hard requirement for any project distributing or caching BMIs, or are there documented cases of cross-version compatibility?
Do header units (import <vector>;) actually reduce this fragility, or do they carry the same version-locking constraints as named modules?
Is shipping headers instead of precompiled modules the only portable option for libraries consumed by external projects?

Tasadduq Burney · Answer

Why GCC 14 rejects GCC 13 C++20 module BMIs
The C++20 standard leaves the Binary Module Interface (BMI) format unspecified. GCC implements BMIs as compiler-internal build artifacts, each stamped with the compiler version that produced them. When GCC 14 encounters a BMI generated by GCC 13, the version stamp triggers a hard rejection, this is by design, not a misconfiguration.

Likely explanation vs confirmed facts

Version-locking is intentional: GCC stamps each BMI with its compiler version. Cross-major-version use is explicitly unsupported.
Header units carry the same constraints: writing import ; still produces a GCC-compiled BMI that bears the compiler's version stamp. They do not provide cross-version portability.
Mixed module/non-module binaries are unaffected: ordinary object files link normally per ABI rules; only the BMI artifacts themselves are version-locked.

Practical steps for this case

Confirm the exact compiler versions on both environments using g++ -dumpfullversion and g++ -dumpversion.
Check that relevant flags are identical: -std=c++20, -fmodules-ts (if applicable), and any ABI or optimization switches.
If distributing BMIs across environments is required, treat exact compiler version parity (including patch release) as a hard requirement, or ship module interface files (.cppm) and headers instead of prebuilt BMIs.
For CI caching, key the cache on the full compiler version string plus the exact flag set that produced the BMI.

One diagnostic detail would help finalize the recommendation: what precise GCC version strings and flag combinations are in use on the developer machines versus the production runners? Once those are known, a targeted cache-invalidation or header-distribution strategy can be confirmed.

C++20 Modules: GCC 13 BMIs Rejected After Toolchain Upgrade to GCC 14

Module builds break at the compiler boundary

Constraints

Open questions

1 answer

Why GCC 14 rejects GCC 13 C++20 module BMIs

Likely explanation vs confirmed facts

Practical steps for this case

Your perspective belongs here.

0 question comments