Federation error codes

Learn the error codes you can receive if composition fails.

When Apollo Gateway attempts to compose the schemas provided by your subgraphs into a supergraph schema, it confirms that:

The subgraphs are valid
The resulting supergraph schema is valid
The gateway has all of the information it needs to execute operations against the resulting schema

If Apollo Gateway encounters an error, composition fails. This document lists subgraph validation and composition error codes, along with their root causes.

Errors

The following errors might be raised during composition:

Error Code / Minimum Federation Version	Description
`DEFAULT_VALUE_USES_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` but is used in the default value of an element visible in the API schema.
`DIRECTIVE_COMPOSITION_ERROR` Since v2.1.0	Error when composing custom directives.
`DIRECTIVE_DEFINITION_INVALID` Since v2.0.0	A built-in or Federation directive has an invalid definition in the schema. Replaces `TAG_DEFINITION_INVALID`.
`DISALLOWED_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` that is not allowed to be `@inaccessible`.
`DOWNSTREAM_SERVICE_ERROR` Since v0.x	Indicates an error in a subgraph service query during query execution in a federated service.
`EMPTY_MERGED_ENUM_TYPE` Since v2.0.0	An enum type has no value common to all the subgraphs that define the type. Merging that type would result in an invalid empty enum type.
`EMPTY_MERGED_INPUT_TYPE` Since v2.0.0	An input object type has no field common to all the subgraphs that define the type. Merging that type would result in an invalid empty input object type.
`ENUM_VALUE_MISMATCH` Since v2.0.0	An enum type that is used as both an input and output type has a value that is not defined in all the subgraphs that define the enum type.
`EXTENSION_WITH_NO_BASE` Since v0.x	A subgraph is attempting to `extend` a type that is not originally defined in any known subgraph.
`EXTERNAL_ARGUMENT_DEFAULT_MISMATCH` Since v2.0.0	An `@external` field declares an argument with a default that is incompatible with the corresponding argument in the declaration(s) of that field in other subgraphs.
`EXTERNAL_ARGUMENT_MISSING` Since v2.0.0	An `@external` field is missing some arguments present in the declaration(s) of that field in other subgraphs.
`EXTERNAL_ARGUMENT_TYPE_MISMATCH` Since v2.0.0	An `@external` field declares an argument with a type that is incompatible with the corresponding argument in the declaration(s) of that field in other subgraphs.
`EXTERNAL_COLLISION_WITH_ANOTHER_DIRECTIVE` Since v2.1.0	The `@external` directive collides with other directives in some situations.
`EXTERNAL_MISSING_ON_BASE` Since v0.x	A field is marked as `@external` in a subgraph but with no non-external declaration in any other subgraph.
`EXTERNAL_ON_INTERFACE` Since v2.0.0	The field of an interface type is marked with `@external`: as external is about marking field not resolved by the subgraph and as interface field are not resolved (only implementations of those fields are), an "external" interface field is nonsensical
`EXTERNAL_TYPE_MISMATCH` Since v0.x	An `@external` field has a type that is incompatible with the declaration(s) of that field in other subgraphs.
`EXTERNAL_UNUSED` Since v0.x	An `@external` field is not being used by any instance of `@key`, `@requires`, `@provides` or to satisfy an interface implementation.
`FIELD_ARGUMENT_DEFAULT_MISMATCH` Since v2.0.0	An argument (of a field/directive) has a default value that is incompatible with that of other declarations of that same argument in other subgraphs.
`FIELD_ARGUMENT_TYPE_MISMATCH` Since v2.0.0	An argument (of a field/directive) has a type that is incompatible with that of other declarations of that same argument in other subgraphs. Replaces `VALUE_TYPE_INPUT_VALUE_MISMATCH`.
`FIELD_TYPE_MISMATCH` Since v2.0.0	A field has a type that is incompatible with other declarations of that field in other subgraphs. Replaces `VALUE_TYPE_FIELD_TYPE_MISMATCH`.
`IMPLEMENTED_BY_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` but implements an element visible in the API schema.
`INPUT_FIELD_DEFAULT_MISMATCH` Since v2.0.0	An input field has a default value that is incompatible with other declarations of that field in other subgraphs.
`INTERFACE_FIELD_NO_IMPLEM` Since v2.0.0	After subgraph merging, an implementation is missing a field of one of the interfaces it implements (which can happen for valid subgraphs).
`INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE` Since v2.3.0	A subgraph has a `@key` on an interface type, but that subgraph does not define an implementation (in the supergraph) of that interface.
`INTERFACE_KEY_NOT_ON_IMPLEMENTATION` Since v2.3.0	A `@key` is defined on an interface type, but is not defined (or is not resolvable) on at least one of the interface implementations.
`INTERFACE_OBJECT_USAGE_ERROR` Since v2.3.0	Error in the usage of the `@interfaceObject` directive.
`INVALID_FEDERATION_SUPERGRAPH` Since v2.1.0	Indicates that a schema provided for an Apollo Federation supergraph is not a valid supergraph schema.
`INVALID_FIELD_SHARING` Since v2.0.0	A field that is non-shareable in at least one subgraph is resolved by multiple subgraphs.
`INVALID_GRAPHQL` Since v2.0.0	A schema is invalid GraphQL: it violates one of the rules of the specification.
`INVALID_LINK_DIRECTIVE_USAGE` Since v2.0.0	An application of the `@link` directive is invalid/does not respect the specification.
`INVALID_LINK_IDENTIFIER` Since v2.1.0	A URL/version for a `@link` feature is invalid/does not respect the specification.
`INVALID_SHAREABLE_USAGE` Since v2.1.2	The `@shareable` Federation directive is used in an invalid way.
`INVALID_SUBGRAPH_NAME` Since v2.0.0	A subgraph name is invalid. (Subgraph names cannot be a single underscore (`_`)).
`KEY_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0	The `fields` argument of a `@key` directive includes some directive applications. This is not supported.
`KEY_FIELDS_HAS_ARGS` Since v2.0.0	The `fields` argument of a `@key` directive includes a field defined with arguments (which is not currently supported).
`KEY_FIELDS_SELECT_INVALID_TYPE` Since v0.x	The `fields` argument of `@key` directive includes a field whose type is a list, interface, or union type. Fields of these types cannot be part of a `@key`.
`KEY_INVALID_FIELDS_TYPE` Since v2.0.0	The value passed to the `fields` argument of a `@key` directive is not a string.
`KEY_INVALID_FIELDS` Since v2.0.0	The `fields` argument of a `@key` directive is invalid (it has invalid syntax, includes unknown fields, ...).
`KEY_UNSUPPORTED_ON_INTERFACE` Since v2.0.0	A `@key` directive is used on an interface, which is only supported when `@link`ing to Federation v2.3 or later.
`LINK_IMPORT_NAME_MISMATCH` Since v2.0.0	The import name for a merged directive (as declared by the relevant `@link(import:)` argument) is inconsistent between subgraphs.
`MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL` Since v2.0.0	In a subgraph, a field is both marked `@external` and has a merged directive applied to it.
`NO_QUERIES` Since v2.0.0	None of the composed subgraphs expose any query.
`ONLY_INACCESSIBLE_CHILDREN` Since v2.0.0	A type visible in the API schema has only `@inaccessible` children.
`OVERRIDE_COLLISION_WITH_ANOTHER_DIRECTIVE` Since v2.0.0	The `@override` directive cannot be used on external fields, nor to override fields with either `@external`, `@provides`, or `@requires`.
`OVERRIDE_FROM_SELF_ERROR` Since v2.0.0	Field with `@override` directive has "from" location that references its own subgraph.
`OVERRIDE_LABEL_INVALID` Since v2.7.0	The `@override` directive `label` argument must match the pattern `/^[a-zA-Z][a-zA-Z0-9_-:./]*$/ or /^percent((d{1,2}(.d{1,8})?\|100))$/`.
`OVERRIDE_ON_INTERFACE` Since v2.3.0	The `@override` directive cannot be used on the fields of an interface type.
`OVERRIDE_SOURCE_HAS_OVERRIDE` Since v2.0.0	Field which is overridden to another subgraph is also marked `@override`.
`PROVIDES_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0	The `fields` argument of a `@provides` directive includes some directive applications. This is not supported.
`PROVIDES_FIELDS_HAS_ARGS` Since v2.0.0	The `fields` argument of a `@provides` directive includes a field defined with arguments (which is not currently supported).
`PROVIDES_FIELDS_MISSING_EXTERNAL` Since v0.x	The `fields` argument of a `@provides` directive includes a field that is not marked as `@external`.
`PROVIDES_INVALID_FIELDS_TYPE` Since v2.0.0	The value passed to the `fields` argument of a `@provides` directive is not a string.
`PROVIDES_INVALID_FIELDS` Since v2.0.0	The `fields` argument of a `@provides` directive is invalid (it has invalid syntax, includes unknown fields, ...).
`PROVIDES_ON_NON_OBJECT_FIELD` Since v2.0.0	A `@provides` directive is used to mark a field whose base type is not an object type.
`PROVIDES_UNSUPPORTED_ON_INTERFACE` Since v2.0.0	A `@provides` directive is used on an interface, which is not (yet) supported.
`QUERY_ROOT_TYPE_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` but is the query root type, which must be visible in the API schema.
`REFERENCED_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` but is referenced by an element visible in the API schema.
`REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH` Since v2.0.0	An argument of a field or directive definition is mandatory in some subgraphs, but the argument is not defined in all the subgraphs that define the field or directive definition.
`REQUIRED_INACCESSIBLE` Since v2.0.0	An element is marked as `@inaccessible` but is required by an element visible in the API schema.
`REQUIRED_INPUT_FIELD_MISSING_IN_SOME_SUBGRAPH` Since v2.0.0	A field of an input object type is mandatory in some subgraphs, but the field is not defined in all the subgraphs that define the input object type.
`REQUIRES_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0	The `fields` argument of a `@requires` directive includes some directive applications. This is not supported.
`REQUIRES_FIELDS_MISSING_EXTERNAL` Since v0.x	The `fields` argument of a `@requires` directive includes a field that is not marked as `@external`.
`REQUIRES_INVALID_FIELDS_TYPE` Since v2.0.0	The value passed to the `fields` argument of a `@requires` directive is not a string.
`REQUIRES_INVALID_FIELDS` Since v2.0.0	The `fields` argument of a `@requires` directive is invalid (it has invalid syntax, includes unknown fields, ...).
`REQUIRES_UNSUPPORTED_ON_INTERFACE` Since v2.0.0	A `@requires` directive is used on an interface, which is not (yet) supported.
`ROOT_MUTATION_USED` Since v0.x	A subgraph's schema defines a type with the name `mutation`, while also specifying a different type name as the root query object. This is not allowed.
`ROOT_QUERY_USED` Since v0.x	A subgraph's schema defines a type with the name `query`, while also specifying a different type name as the root query object. This is not allowed.
`ROOT_SUBSCRIPTION_USED` Since v0.x	A subgraph's schema defines a type with the name `subscription`, while also specifying a different type name as the root query object. This is not allowed.
`SATISFIABILITY_ERROR` Since v2.0.0	Subgraphs can be merged, but the resulting supergraph API would have queries that cannot be satisfied by those subgraphs.
`SHAREABLE_HAS_MISMATCHED_RUNTIME_TYPES` Since v2.0.0	A shareable field return type has mismatched possible runtime types in the subgraphs in which the field is declared. As shared fields must resolve the same way in all subgraphs, this is almost surely a mistake.
`SOURCE_API_HTTP_BASE_URL_INVALID` Since v2.7.0	The `@sourceAPI` directive must specify a valid http.baseURL.
`SOURCE_API_NAME_INVALID` Since v2.7.0	Each `@sourceAPI` directive must take a unique and valid name as an argument.
`SOURCE_API_PROTOCOL_INVALID` Since v2.7.0	Each `@sourceAPI` directive must specify exactly one of the known protocols.
`SOURCE_FEDERATION_VERSION_REQUIRED` Since v2.7.1	Schemas using `@source{API,Type,Field}` directives must `@link`-import v2.7 or later of Federation.
`SOURCE_FIELD_API_ERROR` Since v2.7.0	The `api` argument of the `@sourceField` directive must match a valid `@sourceAPI` name.
`SOURCE_FIELD_HTTP_BODY_INVALID` Since v2.7.0	If `@sourceField` specifies http.body, it must be a valid `JSONSelection` matching available arguments and fields.
`SOURCE_FIELD_HTTP_METHOD_INVALID` Since v2.7.0	The `@sourceField` directive must specify at most one of `http.{GET,POST,PUT,PATCH,DELETE}`.
`SOURCE_FIELD_HTTP_PATH_INVALID` Since v2.7.0	The `@sourceField` directive must specify a valid URL template for `http.{GET,POST,PUT,PATCH,DELETE}`.
`SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD` Since v2.7.0	The `@sourceField` directive must be applied to a field of the `Query` or `Mutation` types, or of an entity type.
`SOURCE_FIELD_PROTOCOL_INVALID` Since v2.7.0	If `@sourceField` specifies a protocol, it must match the corresponding `@sourceAPI` protocol.
`SOURCE_FIELD_SELECTION_INVALID` Since v2.7.0	The `selection` argument of the `@sourceField` directive must be a valid `JSONSelection` that outputs fields of the GraphQL type.
`SOURCE_HTTP_HEADERS_INVALID` Since v2.7.0	The `http.headers` argument of `@source*` directives must specify valid HTTP headers.
`SOURCE_TYPE_API_ERROR` Since v2.7.0	The `api` argument of the `@sourceType` directive must match a valid `@sourceAPI` name.
`SOURCE_TYPE_HTTP_BODY_INVALID` Since v2.7.0	If the `@sourceType` specifies `http.body`, it must be a valid `JSONSelection`.
`SOURCE_TYPE_HTTP_METHOD_INVALID` Since v2.7.0	The `@sourceType` directive must specify exactly one of `http.GET` or `http.POST`.
`SOURCE_TYPE_HTTP_PATH_INVALID` Since v2.7.0	The `@sourceType` directive must specify a valid URL template for `http.GET` or `http.POST`.
`SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY` Since v2.7.0	The `@sourceType` directive must be applied to an object or interface type that also has `@key`.
`SOURCE_TYPE_PROTOCOL_INVALID` Since v2.7.0	The `@sourceType` directive must specify the same protocol as its corresponding `@sourceAPI`.
`SOURCE_TYPE_SELECTION_INVALID` Since v2.0.0	The `selection` argument of the `@sourceType` directive must be a valid `JSONSelection` that outputs fields of the GraphQL type.
`TYPE_DEFINITION_INVALID` Since v2.0.0	A built-in or Federation type has an invalid definition in the schema.
`TYPE_KIND_MISMATCH` Since v2.0.0	A type has the same name in different subgraphs, but a different kind. For instance, one definition is an object type but another is an interface. Replaces `VALUE_TYPE_KIND_MISMATCH`, `EXTENSION_OF_WRONG_KIND`, `ENUM_MISMATCH_TYPE`.
`TYPE_WITH_ONLY_UNUSED_EXTERNAL` Since v2.0.0	A Federation 1 schema has a composite type comprised only of unused external fields. Note that this error can only be raised for Federation 1 schema as Federation 2 schema do not allow unused external fields (and errors with code `EXTERNAL_UNUSED` will be raised in that case). But when Federation 1 schema are automatically migrated to Federation 2 ones, unused external fields are automatically removed, and in rare case this can leave a type empty. If that happens, an error with this code will be raised.
`UNKNOWN_FEDERATION_LINK_VERSION` Since v2.0.0	The version of Federation in a `@link` directive on the schema is unknown.
`UNKNOWN_LINK_VERSION` Since v2.1.0	The version of `@link` set on the schema is unknown.
`UNSUPPORTED_FEATURE` Since v2.1.0	Indicates an error due to feature currently unsupported by Federation.
`UNSUPPORTED_LINKED_FEATURE` Since v2.0.0	Indicates that a feature used in a `@link` is either unsupported or is used with unsupported options.

Removed codes

The following error codes have been removed and are no longer generated by the most recent version of the @apollo/gateway library:

Removed code	Comment
`DUPLICATE_ENUM_DEFINITION`	As duplicate enum definitions is invalid GraphQL, this will now be an error with code `INVALID_GRAPHQL`.
`DUPLICATE_ENUM_VALUE`	As duplicate enum values are invalid in GraphQL, this will now be an error with code `INVALID_GRAPHQL`.
`DUPLICATE_SCALAR_DEFINITION`	As duplicate scalar definitions are invalid in GraphQL, this will now be an error with code `INVALID_GRAPHQL`.
`ENUM_MISMATCH`	Subgraph definitions for an enum are now merged by composition.
`EXTERNAL_USED_ON_BASE`	As there is no type ownership anymore, there is also no particular limitation as to where a field can be external.
`INTERFACE_FIELD_IMPLEM_TYPE_MISMATCH`	This error was thrown by a validation introduced to avoid running into a known runtime bug. Since Federation v2.3, the underlying runtime bug has been addressed and the validation/limitation was no longer necessary and has been removed.
`KEY_FIELDS_MISSING_EXTERNAL`	Using `@external` for key fields is now discouraged, unless the field is truly meant to be external.
`KEY_FIELDS_MISSING_ON_BASE`	Keys can now use any field from any other subgraph.
`KEY_MISSING_ON_BASE`	Each subgraph is now free to declare a key only if it needs it.
`KEY_NOT_SPECIFIED`	Each subgraph can declare a key independently of any other subgraph.
`MULTIPLE_KEYS_ON_EXTENSION`	Every subgraph can have multiple keys, as necessary.
`NON_REPEATABLE_DIRECTIVE_ARGUMENTS_MISMATCH`	Since Federation v2.1.0, the case this error used to cover is now a warning (with code `INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS`) instead of an error.
`PROVIDES_FIELDS_SELECT_INVALID_TYPE`	`@provides` can now be used on fields of interface, union, and list types.
`PROVIDES_NOT_ON_ENTITY`	`@provides` can now be used on any type.
`REQUIRES_FIELDS_HAS_ARGS`	Since Federation v2.1.1, using fields with arguments in a `@requires` is fully supported.
`REQUIRES_FIELDS_MISSING_ON_BASE`	Fields in `@requires` can now be from any subgraph.
`REQUIRES_USED_ON_BASE`	As there is no type ownership anymore, there is also no particular limitation as to which subgraph can use a `@requires`.
`RESERVED_FIELD_USED`	This error was previously not correctly enforced: the service and entities, if present, were overridden; this is still the case.
`VALUE_TYPE_NO_ENTITY`	There is no strong difference between entity and value types in the model (they are just usage patterns), and a type can have keys in one subgraph but not another.
`VALUE_TYPE_UNION_TYPES_MISMATCH`	Subgraph definitions for a union are now merged by composition.

Query plans

Composition hints