Composition

What Is Composition?

Composition is the build-time process that takes one or more source schemas (the schemas exported by your subgraphs) and produces a single, validated, distributable execution schema that the gateway uses to plan and execute distributed queries.

Each subgraph is a standalone GraphQL service that exposes a source schema. On its own, a source schema cannot tell whether its types are compatible with the rest of your system, whether the fields it declares actually overlap correctly with another team's source schema, or whether every entity it references can be resolved somewhere. Composition is the step that answers these questions before anything is deployed.

The pipeline runs on the developer machine or in CI. It validates each source schema individually, checks that the schemas are compatible with each other, merges them into one unified schema, validates the merged result, and finally checks that every reachable field can be resolved by at least one subgraph. If any of those phases produces errors, composition fails and emits diagnostic log codes that point to the exact rule that was violated.

The output of a successful composition is a Fusion archive: a package built around the execution schema. Lookup, key, and ownership information is embedded directly into the schema as directives, so the gateway has everything it needs to plan and execute distributed queries by reading the schema alone. The gateway loads this archive at startup and never sees raw source schemas, only the composed result.

Composition is the safety net of a Fusion deployment. It catches schema conflicts (mismatched types, broken @key references, unreachable fields, ambiguous ownership) at build time, not at request time. A query that succeeds against the gateway is guaranteed to be answerable by your fleet of subgraphs because composition has already proven it.

If you are still onboarding, start with Getting Started. The pages on Entities and Lookups and Field Ownership cover the directives most often referenced by the log codes below.

The Composition Pipeline

Composition runs as an ordered set of phases. Each phase reads the output of the previous one, runs its rules, and either passes the schema to the next phase or aborts with diagnostic errors. Composition halts at the first phase that produces errors. Within a single phase, several errors may be reported together before the pipeline stops at the phase boundary.

flowchart TD
    A[Source Schemas] --> B[1. Parse]
    B --> C[2. Preprocess]
    C --> D[3. Enrich]
    D --> E[4. Validate Source Schemas]
    E --> F[5. Pre-Merge Validation]
    F --> G[6. Merge]
    G --> H[7. Post-Merge Validation]
    H --> I[8. Validate Satisfiability]
    I --> J[Execution Schema]
    B -.fail.-> X[Composition Error]
    C -.fail.-> X
    D -.fail.-> X
    E -.fail.-> X
    F -.fail.-> X
    G -.fail.-> X
    H -.fail.-> X
    I -.fail.-> X

1. Parse Source Schemas

Parses each source schema into an internal representation. This phase catches syntactically invalid SDL (INVALID_GRAPHQL).

2. Preprocess Source Schemas

Normalizes each source schema for composition. This includes applying tag-based exclusions and any version-specific or interop transformations needed before the validation phases run.

3. Enrich Source Schemas

Decorates each schema with metadata extracted from directives, such as key fields, shareability, accessibility flags, and lookup information. The metadata is attached to types and fields so later phases can reason about them efficiently without re-parsing directive arguments.

4. Validate Source Schemas

Runs per-schema validation rules against each source schema independently. Each source schema is checked on its own at this stage, before any cross-schema reasoning. Examples of issues caught here include @external placed on an interface field, malformed @key selection sets, root types with non-default names, and @override referencing the same source schema.

5. Pre-Merge Validation

Validates compatibility across source schemas. This is where the pipeline checks that two source schemas which both define the same type agree on its shape: enum values match, output field types are mergeable, external argument types align, and input types declare the same required fields. Most "two source schemas disagree" diagnostics are surfaced here.

6. Merge Source Schemas

Combines all validated source schemas into a single merged schema. Same-named types are unified, Fusion metadata is applied, and lookup information is recorded so the gateway knows which subgraph owns which field.

7. Post-Merge Validation

Validates the merged schema as a whole. The rules here treat the composed schema as if it were a single GraphQL schema and check global invariants: no merged type is empty, all interfaces are implemented, no field references an inaccessible or internal type, the root query type exposes accessible fields, and default values do not point at inaccessible enum values.

8. Validate Satisfiability

Performs reachability analysis. Starting from the root types, the pipeline walks every reachable field in the merged schema and confirms it can be resolved by at least one subgraph given the available @lookup and @key paths. If a field is reachable from a query but no subgraph can produce it, satisfiability fails with UNSATISFIABLE. This is the last line of defense against shapes that look valid statically but cannot actually be served at runtime.

Common Scenarios

A few rules account for most composition failures. Knowing the shape of the error helps you spot the cause quickly.

Two source schemas return different types for the same field. If Product.price is Float in one source schema and Int in another, composition fails with OUTPUT_FIELD_TYPES_NOT_MERGEABLE. Align the types in the source schemas.

A field is defined in multiple source schemas without @shareable. Defining User.name in both Accounts and Reviews without marking it @shareable produces INVALID_FIELD_SHARING.

# Accounts source schema
type User @key(fields: "id") {
  id: ID!
  name: String!
}

# Reviews source schema
type User @key(fields: "id") {
  id: ID!
  name: String!
}

Composition emits one diagnostic per non-shareable definition, so both source schemas are reported:

The field 'User.name' in schema 'Accounts' must be shareable.

The field 'User.name' in schema 'Reviews' must be shareable.

Add @shareable to User.name in both source schemas that define it. See Field Ownership for when sharing is appropriate.

@key references a field that does not exist on the type. A @key(fields: "sku") on a type that has no sku field fails with KEY_INVALID_FIELDS. The fix is to either add the missing field to the type or correct the selection set in the @key directive. See Entities and Lookups for the rules around key selection sets.

Log Codes Reference

This is the complete list of diagnostic codes the composition pipeline emits, grouped by severity. Codes are stable identifiers and are safe to match on in CI scripts.

The placeholders {0}, {1}, etc. in the message column are replaced with the relevant type, field, or schema name when the diagnostic is emitted.

Errors

Warnings

Diagnosing UNSATISFIABLE Errors

Most composition errors point at a single source schema or definition. UNSATISFIABLE is different. It is raised by the satisfiability validator (phase 8) and tells you that the merged schema as a whole has at least one reachable field that no source schema can serve through the available @lookup and @key paths.

Because the validator weighs every option for reaching a field across every source schema, the diagnostic carries a tree of nested errors that explain why each candidate option failed. Reading that tree from the bottom up is the fastest way to find the gap.

Anatomy of the message

The top-level message names the unreachable field:

Unable to access the field 'Order.shippingAddress'.

Underneath it, indented with two spaces per level, are the nested errors that the validator collected for each option it tried. Common nested messages and what they signal:

Indentation is meaningful: a nested message is the reason its parent option failed. Start at the leaves and work up.

Showing the path the validator took

By default, the top-level message names the failed field but not the path the validator walked to reach it. Enable IncludeSatisfiabilityPaths to extend the message with the path:

Unable to access the field 'Order.shippingAddress' on path 'accounts:Query.viewer<User> -> accounts:User.orders<Order>'.

Each path segment has the shape <schemaName>:<TypeName>.<fieldName><<FieldTypeName>>, and segments are joined with ->. The form is verbose, but unambiguous: it tells you which source schema served each hop and which field type the validator ended up holding.

Set the option via the CLI flag during composition:

nitro fusion compose --include-satisfiability-paths

Paths add noise to short outputs and pay off on any non-trivial graph. Turn them on whenever an UNSATISFIABLE error is hard to triage.

Common causes and fixes

• Missing @lookup for an entity in the target source schema. A field on schema A returns an entity that is also defined in schema B, but B has no lookup that takes the entity's key. Add a lookup on B (typically <entity>(id: ID!): <Entity>) annotated with @lookup. See Entities and Lookups.
• Mismatched @key selections across source schemas. The shared entity has different @key selection sets in different source schemas, so the validator cannot find a key both sides recognize. Align the key selection sets, or add additional @key directives so every key the producer uses is also a key the consumer recognizes.
• @require reaches for a field that is not on the path. A @require(field: "...") references parent fields that the validator cannot resolve given the path it took. Either expose the required field on the parent type along that path, or rewrite the requirement.
• Node interface without a node lookup. A type implements Node but no source schema exposes a node(id: ID!): Node lookup that returns it. Add one in any source schema that owns the entity.

When you fix the root cause, both the top-level UNSATISFIABLE error and its nested children disappear together.

Temporarily ignoring a non-accessible field

When a field is intentionally non-accessible at the moment, for example during an incremental rollout, you can ask the validator to skip it instead of failing composition. Add the qualified field name and the path to skip under the source schema's satisfiability.ignoredNonAccessibleFields in its <schema>-settings.json file:

{
  "satisfiability": {
    "ignoredNonAccessibleFields": {
      "Order.shippingAddress": [
        "accounts:Query.viewer<User> -> accounts:User.orders<Order>"
      ]
    }
  }
}

The key is <TypeName>.<fieldName>. Each value is a list of paths (matching exactly what IncludeSatisfiabilityPaths would print for that field) where the validator should skip the check. The field name and at least one of its paths must match for the error to be silenced.

This setting lives in the per-source-schema settings file (e.g. accounts-settings.json), not in the archive-level composition settings.

[!WARNING] Use this sparingly. It silences a real diagnostic without fixing the underlying gap, so leaving entries in place lets unsatisfiable shapes ship.