What is a feature subgraph?

A feature subgraph is an alternative implementation of a base subgraph in your federated graph. Once it is part of an enabled feature flag, Cosmo builds a separate composition that uses the feature subgraph in place of the base subgraph. Requests that select the flag are served from that pre-built composition. The base subgraph remains unchanged and serves all other requests.

How are feature flags activated per request?

A request selects a flag by sending its name in the X-Feature-Flag header or the feature_flag cookie. If both are set, the header wins. Requests that carry the flag receive the feature composition; all other requests use the base composition.

Cosmo supports shadow mode for migration scenarios. The new subgraph computes the result, but the result is not returned to the client. You compare it with the existing implementation for correctness and performance before you expose the change.

Does enabling or disabling a flag require redeployment?

No. You enable or disable a flag in Cosmo, for example with wgc feature-flag enable, and Cosmo composes the change. Routers that fetch config from Cosmo pick it up on their next poll, every 10 seconds by default plus up to 5 seconds of jitter. Routers that run from a static config file need the updated file. You do not deploy a new router version.

What are the version requirements?

Feature Flags require Cosmo Router v0.95.0 or later and wgc CLI v0.58.0 or later.

Can multiple feature flags be active at once?

On plans that allow more than one, yes. Your plan sets the number: 1 on Developer (free) and Launch, 3 on Scale, a custom number on Enterprise, and no limit on Self Hosted or Enterprise Self Hosted.

Are feature flags available on the free plan?

Yes. The free Developer plan includes 1 feature flag, and the free, open-source Self Hosted plan has no limit. Launch includes 1, Scale 3, and Enterprise a custom number. Enterprise Self Hosted has no limit.

Does Cosmo Router split traffic by percentage?

No. The router does not split traffic. Your load balancer or edge proxy picks which requests get a flag, for example 1% of traffic, and sets the X-Feature-Flag header on them.

What happens if a feature flag composition fails?

The router never receives it. If the base composition or the feature flag composition fails, Cosmo does not produce the feature flag configuration.

Do schema checks cover feature flags?

Yes. A check on a feature subgraph composes every enabled feature flag that contains it. A check on a base subgraph composes the base graph and every enabled feature flag that uses it.

How do I monitor a feature flag rollout?

The router_info Prometheus metric has one series per feature flag configuration, labelled wg_feature_flag. If you turn on circuit breaker metrics (telemetry.metrics.prometheus.circuit_breaker: true), they carry the same label. Metrics and traces are also tagged with the flag name, so you can compare a flag against the base graph in Cosmo Studio or any OpenTelemetry-compatible backend.

How do Cosmo feature flags differ from Apollo progressive override?

Apollo progressive override moves one field at a time, using @override with a label such as percent(25) in the schema. Cosmo feature flags swap whole subgraphs to build a separate composition, and each request selects it by header or cookie.

Do Cosmo Feature Flags replace app-level feature flags?

No. Cosmo Feature Flags work at the federation composition level. You can pair them with a frontend feature flag: when the frontend flag is on for a user, the client sets the Cosmo flag header or cookie for that user.

GraphQL Feature Flags | Cosmo by WunderGraph

The problem

Why GraphQL schema changes are hard to release safely

In a federated GraphQL architecture, one breaking change or performance regression can affect every client immediately. Staging alone cannot show how a change behaves with real production traffic.

Schema changes can affect every client immediately

A breaking change or performance regression can reach every client before teams know how it behaves in production. Without progressive rollout, teams cannot validate changes with a small user segment before rolling out to more traffic.

Rollback depends on another deployment

When a released feature causes problems, teams often have to revert code, redeploy services, or perform a full rollback deployment. That takes time during the exact moment when they need a fast, low risk way to disable the change.

Parallel subgraph changes collide in one schema

Different teams may change their subgraphs in ways that are incompatible with each other. With one schema, they cannot test those changes in isolation. Large environments cannot run a separate set of subgraphs for each feature branch, so teams need isolated compositions on a shared staging environment.

Our solution

Feature flags for safer GraphQL schema delivery

Feature subgraphs are alternative implementations of base subgraphs in your federated graph. When a feature flag is active for a request, Cosmo Router uses the feature subgraph instead of the base subgraph for that request. Teams can roll out schema changes by header or cookie without deploying a new router version.

How it works

Create a feature subgraph as an alternative implementation of a base subgraph.
Group one or more feature subgraphs into a feature flag. Its labels decide which federated graphs it applies to.
Enable the flag. Routers that fetch config from Cosmo pick up the change on their next config poll. Routers that run from a static config file need the updated file.
Requests select the flag with a header or cookie, set by your load balancer, API gateway, or client.
For matching requests, Cosmo Router uses the graph composition with the feature subgraph. Other requests continue using the base composition. To roll back, stop sending the flag or disable it, without deploying new router versions.

Schema-aware. Federation-native. Without deploying new router versions.

Feature flags

What changes with Cosmo

Before Cosmo	With Cosmo
Release schema changes broadly	Gradually roll out to a growing share of traffic, such as 1%, 10%, 50%, then 100%. Your load balancer sets the X-Feature-Flag header on that share, and the router serves the flagged composition
Hard to validate a migration with production traffic	For migrations, use shadow mode to compare the new subgraph with the existing implementation before exposing it
Problematic changes often require rollback deployments	Disable the feature flag without deploying new router versions. Routers pick up the change on their next config poll.
Separate staging environments for each feature	Shared staging with per-developer feature isolation, within your plan's feature flag limit

Activation methods

Activate a flag with a header or cookie

HTTP headers — send the flag name in the X-Feature-Flag header. If a request sends both a header and a cookie, the header wins.
Cookies — send feature_flag=<flag name> in the cookie. An unknown flag name gets the base graph.
Who sets it — your load balancer or API gateway for a share of traffic, or your client for a subset of users.

Key benefits

Release GraphQL changes gradually and roll back without a redeploy

Every Cosmo plan includes feature flags. See the pricing page for plan limits.

Roll out changes to specific user segments

Activate feature subgraphs for requests that send the flag in a header or cookie. Move from small user segments to broader rollout by changing which requests your load balancer or clients send the flag on, without deploying new router versions.

Validate a migration with real traffic before exposing it

For migration scenarios, use shadow mode to compare the new subgraph against the existing implementation for correctness and performance before wider exposure.

Disable risky changes without deploying new router versions

If a feature causes problems, disable the feature flag. Routers pick up the change on their next config poll, without code changes or new router versions.

Serve different graph compositions by request context

Activate feature flags with a header or cookie. Different requests can use different graph compositions from the same router, so you can run isolated experiments and give different users different API experiences.

Let developers test in isolation on shared staging

Each developer can create a feature subgraph for their changes and use a unique header or cookie while testing. Matching requests use their feature subgraph. Other traffic stays on the base composition, without dedicated staging infrastructure per developer. Each developer needs their own flag, so how many can test at once depends on your plan's feature flag limit.

How Cosmo Feature Flags work

01

Replaces one base subgraph.

Create a feature subgraph

Create a feature subgraph linked to the base subgraph it replaces, then publish its schema. When the flag is active, requests that select it use the feature subgraph instead of the base subgraph.

02

Starts disabled.

Create a feature flag

Group one or more feature subgraphs into a feature flag. Its labels must match the label matchers of the federated graphs it applies to. New flags start disabled, so keep the flag disabled until you are ready to test or roll out the change.

03

Enable, then header or cookie.

Enable the flag and send it

Enable the flag. Requests then select it with the X-Feature-Flag header or the feature_flag cookie, set by your load balancer, API gateway, or client. Cosmo Router serves those requests from the feature flag composition.

04

Start small.

Start with a small share of traffic

Send the flag on a small share of requests or for a subset of users, and monitor before wider exposure. For migrations, you can use shadow mode to compare results before exposing them.

05

No router redeploy.

Expand or disable the flag

Widen the share of requests that send the flag over time. If something goes wrong, stop sending it or disable the flag. Routers that fetch config from Cosmo pick up a disabled flag on their next config poll, without deploying new router versions.

What keeps a feature flag rollout safe

New flags start disabled. A flag serves traffic only after you enable it, or create it with --enabled.
A failed composition never reaches the router. If the base or feature flag composition fails, Cosmo does not produce the feature flag configuration.
Schema checks cover enabled flags. A check composes every enabled feature flag that uses the changed subgraph.
An unknown flag name falls back to the base graph. Requests without a matching header or cookie get the base composition.
Each flag shows up in your metrics. The router_info Prometheus metric has one series per feature flag configuration, labelled wg_feature_flag.

Use cases

Where Cosmo Feature Flags help most

Migrate from a monolith to federation safely

Migration

Create a feature subgraph that overrides fields from the monolith using `@override`. Use shadow mode to compare the monolith and federated implementation with real traffic, then gradually increase traffic to the new subgraph while monitoring performance. Once the migration is validated, publish the schema change without the feature flag.

Roll out experimental features to selected user segments

Rollout

Create a feature subgraph for the new implementation, then send the flag on requests from a selected user segment with a header or cookie set by your client or API gateway. Validate performance and gather feedback before expanding rollout by changing which requests get the header or cookie.

Let developers test independently on shared staging

Staging

Each developer creates a feature subgraph for their changes and uses a unique header or cookie while testing. Matching requests use their feature subgraph. Other traffic stays on the base composition, so teams can avoid dedicated staging infrastructure per developer. Each developer needs their own flag, so how many can test at once depends on your plan's feature flag limit.

When to use Cosmo Feature Flags

Use Feature Flags when

You want to release schema changes or new features to a small user segment before a full traffic rollout.
You need to validate changes with real production traffic before exposing them broadly.
You need to disable a problematic feature quickly without deploying a new router version.

Requirements

You need an existing federated graph with base subgraphs. Feature subgraphs act as alternatives to those base subgraphs.
You need Cosmo Router v0.95.0 or later and wgc CLI v0.58.0 or later.
Every Cosmo plan includes feature flags: 1 on Developer (free) and Launch, 3 on Scale, and a custom number on Enterprise. Self Hosted (free, open-source) and Enterprise Self Hosted have no limit.

Roll out GraphQL schema changes safely

Use Cosmo Feature Flags to test, roll out, and disable schema changes without deploying a new router version.

Talk to Sales Read the rollout tutorial

Ready to go deeper?

An overview of feature flag concepts, CLI commands for feature flags and feature subgraphs, and a step-by-step tutorial.

Concepts docs →Feature flag CLI →Feature subgraph CLI →Tutorial →

Safely roll out GraphQL schema changes with feature flags