What is a router compatibility version?

A router compatibility version designates a breaking change in the contract between composition, the router execution configuration, and the router. It is incremented only when backwards compatibility would be unfeasible.

What does the compatibilityVersion property look like?

The property is a colon-delimited string: : . For example, "1:0.1.0" indicates compatibility version 1 and composition library version 0.1.0.

What happens when a router receives an incompatible configuration?

The router produces an error and refuses to start. It will not run with a configuration whose compatibility version exceeds its internal threshold. This is intentional fail-fast behavior.

How does Cosmo Cloud store configurations for different router versions?

Execution configurations are stored discretely by compatibility version at separate CDN addresses. A router polls only the address corresponding to its compatibility version threshold. Older and newer configurations coexist without overwriting each other.

Can I run multiple router versions simultaneously?

Yes. Each router version polls the CDN address for its threshold. Running version 1 and version 2 routers simultaneously during a migration is safe—each receives its appropriate configuration.

How do I manage compatibility version assignments for a federated graph?

Use the wgc federated-graph version set CLI command. The wgc router compatibility-version list command shows currently supported versions.

How often are new compatibility versions released?

New compatibility versions are not intended to be regular occurrences. They are released only when a breaking structural change in the execution configuration makes backwards compatibility unfeasible.

Router Compatibility Versions | Cosmo by WunderGraph

The problem

In a federated architecture, router and composition can fall out of sync

The router depends on execution configurations generated by composition. Breaking changes between how configurations are structured and how routers interpret them can cause production incidents.

Composition and router versions can fall out of sync

The router depends on execution configurations generated by composition. When breaking changes occur in how configurations are structured, older routers may misinterpret them without any warning.

Upgrading routers across a fleet carries coordination risk

Rolling upgrades mean different router versions run simultaneously. Without a mechanism to ensure each version receives a compatible configuration, mixed fleets are risky.

Configuration failures should fail fast, not silently

A router that starts with an incompatible configuration and behaves unexpectedly is harder to debug than one that fails immediately with a clear error message.

Our solution

A version handshake between config and router

Every execution configuration carries a compatibilityVersion. Routers validate it at startup. Cosmo Cloud stores configurations discretely per version. Each router polls only its own address.

How it works

When Cosmo composes a federated graph, the execution configuration includes a compatibilityVersion property.
The format is <compatibility-version>:<composition-package-version> (e.g., "1:0.1.0").
Each router version defines an internal threshold for the maximum compatibility version it accepts.
At startup, the router validates the configuration version against its threshold.
If the configuration version exceeds the threshold, the router fails fast with a clear error.
Cosmo Cloud stores execution configurations discretely by version. Routers poll only the CDN address matching their threshold.

Fail fast on mismatch. Safe upgrades without coordination.

Compatibility Versions

Before & After

Before	With Compatibility Versions
Risk of running routers with incompatible execution configurations	Version handshake prevents incompatible configurations from loading
Silent configuration failures with no clear error message	Router refuses to start with an explicit version mismatch error
Complex coordination required when upgrading router versions	Safe incremental upgrades with each version polling its own config
Single configuration storage shared across all router versions	Discrete CDN storage per compatibility version

Version format

How the version property works

compatibilityVersion: Example: "1:0.1.0" (version:package-version)
Compatibility version: Integer designating the breaking-change tier
Package version: Composition library version that generated the config
Router threshold: Each router version defines a max compatible version
CDN address: Routers poll the address for their threshold version
Error on mismatch: Router refuses to start with a clear error message

How Router Compatibility Versions work

01

Version embedded in every config.

Compose

When Cosmo composes a federated graph, the resulting execution configuration includes a compatibilityVersion property in the format <version>:<package-version> (e.g., "1:0.1.0").

02

Fail fast with a clear error.

Validate

At startup, the router checks the compatibilityVersion in its execution configuration against its internal threshold. If the config version exceeds the threshold, the router produces an error and refuses to start.

03

Discrete storage per version.

Store

Cosmo Cloud stores execution configurations discretely by compatibility version. A router with threshold <=1 polls one CDN address; a router with threshold 2 polls a different one. Configurations never overwrite across versions.

04

Gradual, safe upgrades.

Upgrade

Deploy new router versions alongside existing ones. Each polls the CDN address for its version. Gradually shift traffic from old to new. Retire old instances once the upgrade is complete.

Upgrade patterns

Safe upgrade scenarios

Version handshake makes these patterns safe and predictable.

Rolling production upgrade

Deploy new-version routers alongside existing ones. New routers poll the new CDN address and receive the new configuration. Old routers keep polling the old address. Shift traffic gradually and retire old instances.

Canary deployment

Deploy a single new-version router to a canary pool. It automatically receives the version-appropriate configuration and handles real traffic. Validate before rolling out to the fleet.

Multi-version fleet

Staging runs a newer router version while production stays on the previous one. Each environment receives configuration appropriate to its version. No coordination required.

Fail-fast protection

A router that receives an incompatible configuration refuses to start and logs a clear error. You know immediately what happened, without needing to debug unexpected runtime behavior.

Upgrade routers with confidence

Version handshake prevents incompatible configurations from loading. Mixed fleets work safely.

Start Free Read the Docs

Upgrade routers without breaking running deployments