Federation error codes
Learn the error codes you can receive if composition fails.
When Apollo Gateway attempts to compose the schemas provided by your
- 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 |
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 |
DISALLOWED_INACCESSIBLE Since v2.0.0 | An element is marked as |
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 |
EXTERNAL_ARGUMENT_DEFAULT_MISMATCH Since v2.0.0 | An |
EXTERNAL_ARGUMENT_MISSING Since v2.0.0 | An |
EXTERNAL_ARGUMENT_TYPE_MISMATCH Since v2.0.0 | An |
EXTERNAL_COLLISION_WITH_ANOTHER_DIRECTIVE Since v2.1.0 | The |
EXTERNAL_MISSING_ON_BASE Since v0.x | A field is marked as |
EXTERNAL_ON_INTERFACE Since v2.0.0 | The field of an interface type is marked with |
EXTERNAL_TYPE_MISMATCH Since v0.x | An |
EXTERNAL_UNUSED Since v0.x | An |
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 |
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 |
IMPLEMENTED_BY_INACCESSIBLE Since v2.0.0 | An element is marked as |
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 |
INTERFACE_KEY_NOT_ON_IMPLEMENTATION Since v2.3.0 | A |
INTERFACE_OBJECT_USAGE_ERROR Since v2.3.0 | Error in the usage of the |
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 |
INVALID_LINK_IDENTIFIER Since v2.1.0 | A URL/version for a |
INVALID_SHAREABLE_USAGE Since v2.1.2 | The |
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 |
KEY_FIELDS_HAS_ARGS Since v2.0.0 | The |
KEY_FIELDS_SELECT_INVALID_TYPE Since v0.x | The |
KEY_INVALID_FIELDS_TYPE Since v2.0.0 | The value passed to the |
KEY_INVALID_FIELDS Since v2.0.0 | The |
KEY_UNSUPPORTED_ON_INTERFACE Since v2.0.0 | A |
LINK_IMPORT_NAME_MISMATCH Since v2.0.0 | The import name for a merged directive (as declared by the relevant |
MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL Since v2.0.0 | In a subgraph, a field is both marked |
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 |
OVERRIDE_COLLISION_WITH_ANOTHER_DIRECTIVE Since v2.0.0 | The |
OVERRIDE_FROM_SELF_ERROR Since v2.0.0 | Field with |
OVERRIDE_LABEL_INVALID Since v2.7.0 | The |
OVERRIDE_ON_INTERFACE Since v2.3.0 | The |
OVERRIDE_SOURCE_HAS_OVERRIDE Since v2.0.0 | Field which is overridden to another subgraph is also marked |
PROVIDES_DIRECTIVE_IN_FIELDS_ARG Since v2.1.0 | The |
PROVIDES_FIELDS_HAS_ARGS Since v2.0.0 | The |
PROVIDES_FIELDS_MISSING_EXTERNAL Since v0.x | The |
PROVIDES_INVALID_FIELDS_TYPE Since v2.0.0 | The value passed to the |
PROVIDES_INVALID_FIELDS Since v2.0.0 | The |
PROVIDES_ON_NON_OBJECT_FIELD Since v2.0.0 | A |
PROVIDES_UNSUPPORTED_ON_INTERFACE Since v2.0.0 | A |
QUERY_ROOT_TYPE_INACCESSIBLE Since v2.0.0 | An element is marked as |
REFERENCED_INACCESSIBLE Since v2.0.0 | An element is marked as |
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 |
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 |
REQUIRES_FIELDS_MISSING_EXTERNAL Since v0.x | The |
REQUIRES_INVALID_FIELDS_TYPE Since v2.0.0 | The value passed to the |
REQUIRES_INVALID_FIELDS Since v2.0.0 | The |
REQUIRES_UNSUPPORTED_ON_INTERFACE Since v2.0.0 | A |
ROOT_MUTATION_USED Since v0.x | A subgraph's schema defines a type with the name |
ROOT_QUERY_USED Since v0.x | A subgraph's schema defines a type with the name |
ROOT_SUBSCRIPTION_USED Since v0.x | A subgraph's schema defines a type with the name |
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 |
SOURCE_API_NAME_INVALID Since v2.7.0 | Each |
SOURCE_API_PROTOCOL_INVALID Since v2.7.0 | Each |
SOURCE_FEDERATION_VERSION_REQUIRED Since v2.7.1 | Schemas using |
SOURCE_FIELD_API_ERROR Since v2.7.0 | The |
SOURCE_FIELD_HTTP_BODY_INVALID Since v2.7.0 | If |
SOURCE_FIELD_HTTP_METHOD_INVALID Since v2.7.0 | The |
SOURCE_FIELD_HTTP_PATH_INVALID Since v2.7.0 | The |
SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD Since v2.7.0 | The |
SOURCE_FIELD_PROTOCOL_INVALID Since v2.7.0 | If |
SOURCE_FIELD_SELECTION_INVALID Since v2.7.0 | The |
SOURCE_HTTP_HEADERS_INVALID Since v2.7.0 | The |
SOURCE_TYPE_API_ERROR Since v2.7.0 | The |
SOURCE_TYPE_HTTP_BODY_INVALID Since v2.7.0 | If the |
SOURCE_TYPE_HTTP_METHOD_INVALID Since v2.7.0 | The |
SOURCE_TYPE_HTTP_PATH_INVALID Since v2.7.0 | The |
SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY Since v2.7.0 | The |
SOURCE_TYPE_PROTOCOL_INVALID Since v2.7.0 | The |
SOURCE_TYPE_SELECTION_INVALID Since v2.0.0 | The |
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 |
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 |
UNKNOWN_FEDERATION_LINK_VERSION Since v2.0.0 | The version of Federation in a |
UNKNOWN_LINK_VERSION Since v2.1.0 | The version of |
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 |
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 |
DUPLICATE_ENUM_VALUE | As duplicate enum values are invalid in GraphQL, this will now be an error with code |
DUPLICATE_SCALAR_DEFINITION | As duplicate scalar definitions are invalid in GraphQL, this will now be an error with code |
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 |
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 |
PROVIDES_FIELDS_SELECT_INVALID_TYPE |
|
PROVIDES_NOT_ON_ENTITY |
|
REQUIRES_FIELDS_HAS_ARGS | Since Federation v2.1.1, using fields with arguments in a |
REQUIRES_FIELDS_MISSING_ON_BASE | Fields in |
REQUIRES_USED_ON_BASE | As there is no type ownership anymore, there is also no particular limitation as to which subgraph can use a |
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. |