Apollo Federation 错误代码

组合错误代码参考

当GraphOS 尝试将您提供的子图组合成 supergraph 架构，它确认：

子图拥有有效的 GraphQL 和 Federation 语法
生成的 supergraph 架构是有效的
graph 路由器或 gateway 拥有执行针对该结构操作所需的所有信息

如果组合失败，则无法生成新的 supergraph 架构。此文档列出子图验证和组合错误代码及其根本原因。

ⓘ 注意

组合可能会标记出潜在改进或提示有关 schemas（这些 schemas 在技术上有效）。这些提示不是错误，而是作为 composition 构建步骤的一部分进行记录。了解更多信息，请参阅组合提示文档。

错误

以下错误可能在组合期间引发：

错误代码 / 最低 Federation 版本	描述
`DEFAULT_VALUE_USES_INACCESSIBLE` 自 v2.0.0	一个元素被标记为`@inaccessible`，但在可见于API模式的元素的默认值中被使用。
`DIRECTIVE_COMPOSITION_ERROR` 自v2.1.0以来	组合自定义指令时出现错误。
`DIRECTIVE_DEFINITION_INVALID` 自 v2.0.0	内置或联盟指令在模式中定义无效。替代`TAG_DEFINITION_INVALID`。
`DISALLOWED_INACCESSIBLE` 自 v2.0.0	一个标记为`@inaccessible`的元素不允许被标记为`@inaccessible`。
`DOWNSTREAM_SERVICE_ERROR` 自v0.x以来	表示在联盟服务查询执行期间，子图服务subgraph查询中出现错误。
`EMPTY_MERGED_ENUM_TYPE` 自 v2.0.0	枚举类型定义没有在所有subgraphs中定义的值。合并该类型会导致无效的空枚举类型。
`EMPTY_MERGED_INPUT_TYPE` 自 v2.0.0	输入对象类型没有在所有定义该类型的subgraphs中定义的公共字段。合并该类型会导致无效的空输入对象类型。
`ENUM_VALUE_MISMATCH` 自 v2.0.0	用作输入和输出类型的枚举类型具有在定义该枚举类型的所有subgraphs中未定义的值。
`EXTENSION_WITH_NO_BASE` 自v0.x以来	一个subgraph试图`扩展`在一个已知子图中原始未定义的类型。
`EXTERNAL_ARGUMENT_DEFAULT_MISMATCH` 自 v2.0.0	一个`@external`字段声明了一个与该字段在其他subgraphs声明中相应的参数不兼容的参数。
`EXTERNAL_ARGUMENT_MISSING` 自 v2.0.0	一个`@external`字段缺失某些在其他subgraphs字段声明中存在的参数。
`EXTERNAL_ARGUMENT_TYPE_MISMATCH` 自 v2.0.0	一个`@external`字段声明了一个与该字段在其他subgraphs声明中相应的参数不兼容的类型。
`EXTERNAL_COLLISION_WITH_ANOTHER_DIRECTIVE` 自v2.1.0以来	在某些情况下，`@external`指令与其他指令冲突。
`EXTERNAL_MISSING_ON_BASE` 自v0.x以来	字段在子图中被标记为`@external`，但没有任何其他子图中的非外部声明。
`EXTERNAL_ON_INTERFACE` 自 v2.0.0	接口类型的字段通过`@external`标识：因为“外部”是用来标记不被子图解析的字段，而接口字段不进行解析（只有那些字段的实现会被解析），所以一个“外部”接口字段是没有意义的。
`EXTERNAL_TYPE_MISMATCH` 自v0.x以来	一个`@external`字段有一个与其他子图中该字段的声明不兼容的类型。
`EXTERNAL_UNUSED` 自v0.x以来	一个`@external`字段未被任何`@key`、`@requires`、`@provides`实例使用，也没有用于满足接口实现的任何要求。
`FIELD_ARGUMENT_DEFAULT_MISMATCH` 自 v2.0.0	字段（或指令）的一个参数的默认值与其他子图中相同参数的其他声明不兼容。
`FIELD_ARGUMENT_TYPE_MISMATCH` 自 v2.0.0	字段（或指令）的一个参数的类型与其他子图中相同参数的其他声明不兼容。替换`VALUE_TYPE_INPUT_VALUE_MISMATCH`。
`FIELD_TYPE_MISMATCH` 自 v2.0.0	字段有一个与其他子图中该字段的声明不兼容的类型。替换`VALUE_TYPE_FIELD_TYPE_MISMATCH`。
`IMPLEMENTED_BY_INACCESSIBLE` 自 v2.0.0	元素被标记为`@inaccessible`，但它实现了API模式中可见的元素。
`INPUT_FIELD_DEFAULT_MISMATCH` 自 v2.0.0	一个输入字段有一个与其他子图中该字段的其他声明不兼容的默认值。
`INTERFACE_FIELD_NO_IMPLEM` 自 v2.0.0	在子图合并后，一个实现缺少它实现的一个接口的一个字段（这在有效的子图中可能发生）。
`INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE` 自v2.3.0起	一个子图在接口类型上有`@key`，但该子图没有定义（在supergraph中）该接口的实现。
`INTERFACE_KEY_NOT_ON_IMPLEMENTATION` 自v2.3.0起	一个`@key`定义在接口类型上，但没有定义（或不可解析）在至少一个接口实现上。
`INTERFACE_OBJECT_USAGE_ERROR` 自v2.3.0起	`@interfaceObject`指令的使用错误。
`INVALID_FEDERATION_SUPERGRAPH` 自v2.1.0以来	表示为Apollo Federation超图提供的模式不是一个有效的supergraph模式。
`INVALID_FIELD_SHARING` 自 v2.0.0	至少有一个子图中不可共享的字段被多个子图解析。
`INVALID_GRAPHQL` 自 v2.0.0	模式无效GraphQL：它违反了规范中的某个规则。
`INVALID_LINK_DIRECTIVE_USAGE` 自 v2.0.0	@link`@link` 指令的使用无效/未遵循规范。
`无效的链接标识符` 自v2.1.0以来	@link`@link` 功能的 URL/版本无效/未遵循规范。
`无效的可分享用法` 自 v2.1.2 版本起	@shareable`@shareable` 联邦指令以无效方式使用。
`无效的子图名称` 自 v2.0.0	子图名称无效。 (子图名称不能仅有一个下划线 (`_`))。
`在字段中使用键指令` 自v2.1.0以来	@key`@key` 指令的 `fields` 参数包括一些指令应用。这是不被支持的。
`@key 的字段有参数` 自 v2.0.0	@key`@key` 指令的 `fields` 参数包括一个以参数定义的字段（目前不支持）。
`@key 字段选择无效类型` 自v0.x以来	@key`@key` 指令的 `fields` 参数包括其类型为列表、接口或联合类型的字段。这些类型的字段不能是 `@key` 的一部分。
`@key 字段无效类型` 自 v2.0.0	传递给 @key 指令的 `fields` 参数的值不是字符串。
`@key 字段无效` 自 v2.0.0	@key`@key` 指令的 `fields` 参数无效（语法无效，包含未知字段，……）。
`@key 在接口上不支持` 自 v2.0.0	在接口上使用 @key 指令，这只在连接到 Federation v2.3 或更高版本时受支持。
`合并指令的导入名称不匹配` 自 v2.0.0	合并指令（由相关 @link(import:) 参数声明）的导入名称在子图中不一致。
`在外部子图上应用合并指令` 自 v2.0.0	在子图中，一个字段同时被标记为 @external 并对其应用了合并指令。
`没有查询` 自 v2.0.0	没有组成的子图暴露任何查询。
`只有不可访问的孩子` 自 v2.0.0	API 模式表中可见的类型只有 @inaccessible 的孩子。
`与另一个指令冲突覆盖` 自 v2.0.0	@override 指令不能用于外部字段，也不能用来覆盖带有 @external、@provides 或 @requires 的字段。
`来自自身的覆盖错误` 自 v2.0.0	字段含`@override` 指令具有“from”位置，引用了其自身的子图。
`OVERRIDE_LABEL_INVALID` 自v2.7.0起	指令`@override`的`label`参数必须匹配模式`/^[a-zA-Z][a-zA-Z0-9_-:./]*$/或/^percent((d{1,2}(.d{1,8})?\|100))$/`。
`OVERRIDE_ON_INTERFACE` 自v2.3.0起	指令`@override`不能用于接口类型的字段。
`OVERRIDE_SOURCE_HAS_OVERRIDE` 自 v2.0.0	将字段重写为另一个子图的字段也标记为`@override`。
`PROVIDES_DIRECTIVE_IN_FIELDS_ARG` 自v2.1.0以来	指令`@provides`的fields参数包含一些指令应用。这不被支持。
`PROVIDES_FIELDS_HAS_ARGS` 自 v2.0.0	指令`@provides`的fields参数包含使用参数定义的字段（目前不支持）。
`PROVIDES_FIELDS_MISSING_EXTERNAL` 自v0.x以来	指令`@provides`的fields参数包含未标记为`@external`的字段。
`PROVIDES_INVALID_FIELDS_TYPE` 自 v2.0.0	传递给指令`@provides`的fields参数的值不是字符串。
`PROVIDES_INVALID_FIELDS` 自 v2.0.0	指令`@provides`的fields参数无效（存在无效语法、包含未知字段等）。
`PROVIDES_ON_NON_OBJECT_FIELD` 自 v2.0.0	指令`@provides`用于标记基本类型不是对象类型的字段。
`PROVIDES_UNSUPPORTED_ON_INTERFACE` 自 v2.0.0	指令`@provides`在接口上使用，这可能还不被支持。
`QUERY_ROOT_TYPE_INACCESSIBLE` 自 v2.0.0	元素被标记为`@inaccessible`但它是查询根类型，必须在API模式中可见。
`REFERENCED_INACCESSIBLE` 自 v2.0.0	元素被标记为`@inaccessible`但被API模式中的一个可见元素引用。
`REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH` 自 v2.0.0	字段或指令定义的一个参数在一些子图中是强制性的，但该参数未定义在定义字段或指令定义的所有子图中。
`REQUIRED_INACCESSIBLE` 自 v2.0.0	元素被标记为`@inaccessible`但被API模式中的一个可见元素所需要。
`REQUIRED_INPUT_FIELD_MISSING_IN_SOME_SUBGRAPH` 自 v2.0.0	在A字段中，某些子图要求输入对象类型必须包含该字段，但在定义输入对象类型的所有子图中并非都对该字段进行了定义。
`REQUIRES_DIRECTIVE_IN_FIELDS_ARG` 自v2.1.0以来	@requires指令的 `fields` 参数包含一些指令应用。这是不被支持的。
`REQUIRES_FIELDS_MISSING_EXTERNAL` 自v0.x以来	@requires指令的 `fields` 参数包含一个未标记为 `@external` 的字段。
`REQUIRES_INVALID_FIELDS_TYPE` 自 v2.0.0	传递给@requires指令的`fields`参数的值不是字符串。
`REQUIRES_INVALID_FIELDS` 自 v2.0.0	@requires指令的 `fields` 参数无效（语法有误，包含未知字段等）。
`REQUIRES_UNSUPPORTED_ON_INTERFACE` 自 v2.0.0	在接口上使用了@requires指令，而这目前不支持。
`ROOT_MUTATION_USED` 自v0.x以来	子图的模式定义了一个名为mutation的类型，同时也指定了不同的类型名称作为根查询对象。这是不允许的。
`ROOT_QUERY_USED` 自v0.x以来	子图的模式定义了一个名为query的类型，同时也指定了不同的类型名称作为根查询对象。这是不允许的。
`ROOT_SUBSCRIPTION_USED` 自v0.x以来	子图的模式定义了一个名为subscription的类型，同时也指定了不同的类型名称作为根查询对象。这是不允许的。
`SATISFIABILITY_ERROR` 自 v2.0.0	子图可以合并，但生成的超图API将包含无法由那些子图满足的查询。
`SHAREABLE_HAS_MISMATCHED_RUNTIME_TYPES` 自 v2.0.0	可共享字段返回类型在声明字段的子图中具有不匹配的可能运行时类型。由于所有子图中共享字段必须以相同的方式解决，这几乎肯定是错误。
`SOURCE_API_HTTP_BASE_URL_INVALID` 自v2.7.0起	@sourceAPI指令必须指定一个有效的http.baseURL。
`SOURCE_API_NAME_INVALID` 自v2.7.0起	每个@sourceAPI指令必须接受一个独特且有效的名称作为参数。
`SOURCE_API_PROTOCOL_INVALID` 自v2.7.0起	每个@sourceAPI指令必须指定已知的协议之一。
`SOURCE_FEDERATION_VERSION_REQUIRED` 自v2.7.1起	使用@source{API,Type,Field}指令的架构必须使用Federation v2.7 或更高版本的@link imported。
`SOURCE_FIELD_API_ERROR` 自v2.7.0起	@sourceField指令的api参数必须匹配一个有效的@sourceAPI名称。
`SOURCE_FIELD_HTTP_BODY_INVALID` 自v2.7.0起	如果`@sourceField`指定了http.body，它必须是一个匹配可用参数和字段的`JSONSelection`。
`SOURCE_FIELD_HTTP_METHOD_INVALID` 自v2.7.0起	@sourceField指令必须指定http.{GET,POST,PUT,PATCH,DELETE}中最多一个。
`SOURCE_FIELD_HTTP_PATH_INVALID` 自v2.7.0起	@sourceField指令必须指定http.{GET,POST,PUT,PATCH,DELETE}的有效URL模板。
`SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD` 自v2.7.0起	@sourceField指令必须应用于Query或Mutation类型的字段，或者应用在类型为实体类型的字段上。
`SOURCE_FIELD_PROTOCOL_INVALID` 自v2.7.0起	如果@sourceField指定了协议，它必须与相应的@sourceAPI协议匹配。
`SOURCE_FIELD_SELECTION_INVALID` 自v2.7.0起	@sourceField指令的selection参数必须是一个有效的`JSONSelection`，该参数输出GraphQL类型的字段。
`SOURCE_HTTP_HEADERS_INVALID` 自v2.7.0起	@source*指令的http.headers参数必须指定有效的HTTP头。
`SOURCE_TYPE_API_ERROR` 自v2.7.0起	@sourceType指令的api参数必须与有效的@sourceAPI名称匹配。
`SOURCE_TYPE_HTTP_BODY_INVALID` 自v2.7.0起	如果@sourceType指定了http.body，它必须是一个有效的JSONSelection。
`SOURCE_TYPE_HTTP_METHOD_INVALID` 自v2.7.0起	@sourceType指令必须指定http.GET或http.POST中确切的一个。
`SOURCE_TYPE_HTTP_PATH_INVALID` 自v2.7.0起	@sourceType指令必须指定http.GET或http.POST的有效URL模板。
`SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY` 自v2.7.0起	@sourceType指令必须应用于具有@key的对象或接口类型。
`SOURCE_TYPE_PROTOCOL_INVALID` 自v2.7.0起	@sourceType指令必须指定与相应的@sourceAPI相同的协议。
`SOURCE_TYPE_SELECTION_INVALID` 自 v2.0.0	@sourceType指令的selection参数必须是一个有效的JSONSelection，该参数输出GraphQL类型的字段。
`TYPE_DEFINITION_INVALID` 自 v2.0.0	在模式中有一个内置或Federation类型有无效的定义。
`TYPE_KIND_MISMATCH` 自 v2.0.0	在同一子图中，一个类型的名称可能不同，但其类型不同。例如，一个定义是对象类型，而另一个是接口。替换 `VALUE_TYPE_KIND_MISMATCH`、`EXTENSION_OF_WRONG_KIND`、`ENUM_MISMATCH_TYPE`。
`只有未使用的外部类型` 自 v2.0.0	Federation 1 项具有只包含未使用外部字段的复合类型。请注意，此错误只会针对 Federation 1 项引发，因为 Federation 2 项不允许使用未使用的字段（在这种情况下，将引发带有代码 `EXTERNAL_UNUSED` 的错误）。但是，当 Federation 1 项自动迁移到 Federation 2 项时，未使用的字段将自动删除，在罕见的情况下，这可能导致类型为空。如果发生这种情况，将引发具有此代码的错误。
`未知联邦链接版本` 自 v2.0.0	在架构上的 `@link` 指令中，联邦的版本是未知的。
`未知链接版本` 自v2.1.0以来	在架构上设置的 `@link` 的版本是未知的。
`不支持的功能` 自v2.1.0以来	表示由于 Federation 当前不支持该功能而引发错误。
`不支持链接的功能` 自 v2.0.0	表示在 `@link` 中使用的功能既不受支持，或者使用不支持的选择。

已删除的代码

以下错误代码已被删除，并由最新版本的 @apollo/gateway 库不再生成：

已删除代码	注释
`重复枚举定义`	由于重复枚举定义是无效的 GraphQL，这现在将是一个带有代码 `INVALID_GRAPHQL` 的错误。
`重复枚举值`	由于在 GraphQL 中重复枚举值是无效的，这现在将是一个带有代码 `INVALID_GRAPHQL` 的错误。
`重复标量定义`	由于在 GraphQL 中重复标量定义是无效的，这现在将是一个带有代码 `INVALID_GRAPHQL` 的错误。
`枚举不匹配`	子图中对枚举的定义现在通过组合进行合并。
`在基上使用外部字段`	由于不再有类型权限，因此现在没有特定限制，说明字段可以被外部使用。
`接口字段实现类型不匹配`	此错误由引入的验证引发，以避免遇到已知运行时错误。由于 Federation v2.3，底层的运行时错误已被解决，因此不再需要验证/限制，并且已将其删除。
`外部键字段缺失`	现在不建议对键字段使用 `@external`，除非该字段确实意味着要外部使用。
`在基上缺少键字段`	键现在可以使用任何其他子图的任何字段。
`在基上缺少键`	每个子图现在只有在需要时才能声明一个键。
`未指定键`	每个子图可以独立于任何其他子图声明一个键。
`扩展时多处指定了多个键`	每个子图可以拥有所需的多个键。
`不重复的指令参数不匹配`	从 Federation v2.1.0 版本开始，此错误原来覆盖的情况现在变为警告（代码 `INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS`）而不是错误。
`提供字段选择无效类型`	`@provides`现在可以在接口、联合和列表类型的字段上使用。
`@provides不应用于实体`	`@provides`现在可以用于任何类型。
`requires字段有参数`	从 Federation v2.1.1 版本开始，在 @requires 中使用带参数的 fields 完全被支持。
`requires字段在基图缺失`	字段在 @requires 中现在可以从任何子图中获取。
`在基图中使用 requires`	由于不再有类型所有权，没有哪个子图可以使用 @requires 的特定限制。
`使用了保留字段`	此错误以前执行不正确：服务和实体（如果存在）被覆盖；情况依然是如此。
`值类型无实体`	在模型中（它们只是使用模式），实体类型和值类型之间没有强烈的区别，并且类型可以在一个子图中具有键但在另一个子图中没有。
`值类型的联合类型不匹配`	现在通过合成合并联合的子图定义。

查询计划

合成提示