What happens to routers if a composition fails?

Nothing changes. When composition fails, the control plane holds the last successful composed schema active on all routers. No partial updates are pushed. Routers continue serving requests against the previously valid configuration.

What causes a composition failure?

The most common causes are type conflicts between subgraphs (two subgraphs defining the same type differently), missing entity references (a subgraph referencing a key field that another subgraph does not provide), and federation directive violations (incorrect use of @key, @external, @requires, or @provides).

How do I see what changed between two compositions?

Open the Compositions page in Studio, select any two composition records, and view the schema diff. Additions, removals, and modifications are shown at the field level.

Can I trigger composition without publishing a schema change?

Composition runs automatically on publish. To validate before publishing, run `wgc subgraph check` — this tests composition without pushing any changes.

How quickly do routers pick up a new composition?

Near-real-time. When composition succeeds, the new configuration is pushed to the CDN immediately. Routers poll for updates and hot-reload the new configuration without restarting or dropping traffic.

Can I roll back to a previous composition?

Yes. Router configurations are versioned. You can pin a router to a specific composition version via the CLI or Studio if a regression is introduced.

Does schema composition work with a self-hosted Cosmo deployment?

Yes. The composition engine runs as part of the control plane, which can be self-hosted. The behavior is identical to Cosmo Cloud.

GraphQL Schema Composition | Cosmo by WunderGraph

The problem

Why federated graph composition fails

Merging subgraph schemas into a single supergraph is harder than it looks. Without proper tooling, type conflicts, missing references, and federation directive issues can stay hidden until deployment.

Composition failures surface too late

Type conflicts, missing references, and broken federation references can go unnoticed until a subgraph change reaches deployment. By then, teams may already be dealing with production risk.

No clear record of what changed or who changed it

When a federated graph starts behaving unexpectedly, teams need to know what changed, when it changed, and who triggered it. Without composition history, root cause analysis gets slower.

Manual merging does not scale across teams

Maintaining a hand-merged supergraph schema breaks down as more teams publish subgraph changes. Conflicts become harder to track, and the merge process becomes a bottleneck.

Our solution

Automatic composition with complete history

Cosmo's composition engine runs on every subgraph publish. It validates the full federated graph, distributes new router configurations on success, and records every composition attempt with inputs, outputs, errors, and version history.

What happens on every publish

A developer publishes a subgraph with `wgc subgraph publish`. The publish triggers composition.
The composition engine validates the new schema against every other subgraph in the federated graph, checking for type conflicts, missing references, and federation directive compliance.
If composition succeeds, the new router configuration is distributed through the CDN, and routers hot reload the update.
If composition fails, the error is recorded with detailed, actionable error messages. The existing valid schema remains active.
Each composition attempt is saved with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions.

Failed compositions do not replace the existing valid router configuration.

Schema composition

Before & After

Before Cosmo	With Cosmo
Manual schema merging with potential errors	Automatic composition on every publish
No visibility into composition history	Complete audit trail of all compositions
Difficult to identify what changed	Visual diff between schema versions
Unclear which version routers are using	Clear indication of active router configuration

Composition engine

What the engine validates

Type compatibility: conflicting definitions across subgraphs fail composition.
Entity references: referenced entities and relationships are validated across subgraphs.
Federation directive compliance: federation directives are checked for composition compatibility.
Missing fields: fields or references required for composition surface before routers receive the change.

Key benefits

Ship subgraph changes without breaking the graph

Available on Free, Pro, and Enterprise.

Composition runs automatically on every publish

Included

No manual merging, no separate composition step. When a developer publishes a subgraph, Cosmo automatically composes it against the other subgraphs in the federated graph. The result is recorded in Studio with the composition outcome and any errors.

Failed compositions do not reach production routers

Included

When composition fails, the existing valid schema remains active. The failure is recorded with detailed, field-level error information so teams can see which types, fields, references, or federation directive compliance issues caused the conflict.

Every composition attempt is recorded

Included

The composition history tracks each attempt with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions. Teams can use that history for audits, debugging, and understanding graph changes.

See exactly what each publish changed

Included

Studio shows visual diffs between schema versions, including additions, removals, and modifications. Teams can see what changed in the federated graph without manually reconstructing schema changes across services.

Routers receive successful configurations automatically

Included

When composition succeeds, the new router configuration is pushed to the CDN. Routers periodically check for updates and hot reload the new configuration, enabling zero-downtime router updates.

How schema composition works

01

One command triggers everything.

Publish a subgraph

Run `wgc subgraph publish` to publish a subgraph schema. The publish triggers composition in the control plane.

02

All subgraphs validated together.

Composition is attempted

The control plane validates the new schema against every other subgraph. Type conflicts, missing references, and federation directive compliance issues surface before routers receive the change.

03

Zero-downtime hot reload.

Success: router configuration updates

If composition succeeds, the new router configuration is pushed to the CDN. Routers periodically check for updates and hot reload the new configuration, enabling zero-downtime updates.

04

No partial updates to routers.

Failure: existing valid schema stays active

If composition fails, the existing valid schema remains active. The error is logged with detailed, field-level information so the team can understand the conflict and publish a corrected schema.

05

Full audit trail, always.

History is recorded

Every composition attempt is recorded with trigger details, timestamps, inputs, outputs, errors, and resulting schema versions. Studio gives teams a composition history they can use for audits, debugging, and understanding graph changes.

Use cases

When teams rely on composition

Continuous schema delivery

Daily deploys

A team publishing multiple subgraph updates a day needs each change to compose safely. Each `wgc subgraph publish` triggers composition with the other subgraphs in the federated graph. If composition fails, the existing valid schema remains active. If it succeeds, the new router configuration is made available to routers.

Debugging a composition failure

Studio

A new subgraph update fails to compose. The Compositions page in Studio shows detailed error messages indicating which types, fields, or federation directive compliance issues caused the conflict. Developers can review the input schemas and understand the root cause.

Compliance and audit trail

Audit

A compliance review requires documentation of schema changes over the past quarter. The Compositions page provides a complete history of composition attempts with timestamps, triggering users, and resulting schemas. Teams can compare schema versions with visual diffs.

Multi-team coordination

Teams

When multiple teams publish to the same federated graph, composition history helps show which publish triggered a composition failure. Detailed error messages and trigger tracking help teams identify what changed, who triggered it, and where to investigate.

When to use schema composition

When to use

You are building a federated GraphQL graph with multiple subgraphs and need reliable, automatic composition.
Multiple teams publish subgraph changes and you need shared composition history for auditing, debugging, and change tracking.
You want failed compositions to leave the existing valid router configuration active instead of replacing it.

When not to use

You are running a single non-federated GraphQL graph with no subgraphs to compose.
You need pre-publish validation in CI/CD. Use Schema Checks before publishing, then rely on composition to validate published subgraph changes against the federated graph.

Start composing federated subgraphs in minutes

Free tier. No credit card. Full composition history from day one.

Start Free See the docs

Ready to go deeper?

Full reference for publish commands, composition error types, Studio interface, and router version management.

Composition docs →Publish CLI reference →

Your subgraphs compose automatically — and protect the router when they don't

Why federated graph composition fails

Composition failures surface too late

No clear record of what changed or who changed it

Manual merging does not scale across teams

Automatic composition with complete history

What happens on every publish

Before & After

What the engine validates

Ship subgraph changes without breaking the graph

Composition runs automatically on every publish

Failed compositions do not reach production routers

Every composition attempt is recorded

See exactly what each publish changed

Routers receive successful configurations automatically

How schema composition works

Publish a subgraph

Composition is attempted

Success: router configuration updates

Failure: existing valid schema stays active

History is recorded

When teams rely on composition

Continuous schema delivery

Debugging a composition failure

Compliance and audit trail

Multi-team coordination

When to use schema composition

When to use

When not to use

Start composing federated subgraphs in minutes

Ready to go deeper?

GraphQL schema composition