本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 问题排查 **迁移现已开放** Amazon 代理注册表已在新`agent-registry`命名空间下启动。2026 年 10 月 30 日将停止对公共预览版`bedrock-agentcore`命名空间的支持。有关迁移说明，请参阅[注册表迁移综合指南](registry-faq.md)。 ## 架构验证错误 创建不同类型的记录时，您可能会看到描述符的验证异常。有关有效的架构，请参阅[支持的记录类型](registry-supported-record-types.md)部分。 常见错误： + “描述符类型'a2a'不支持架构版本'0.3.0'。” — SchemaVersion 字段值应`0.3`改为。`0.3.0`这与 A2A 协议网站上的[官方 A2A 协议版本描述](https://a2a-protocol.org/latest/specification/#446-agentinterface)一致：“使用每个主要版本支持的最新次要版本”。 + “架构验证失败：内容不符合描述符类型'a2a'的架构版本'0.3'。” — 您可以在 “[支持的记录类型](registry-supported-record-types.md)” 上找到架构。请注意，内容将根据 json 架构definitions/AgentCard 中的 \#/进行验证。 ## 记录同步错误 当您使用同步功能创建或更新记录时，该记录可能会转换为 CREATE\_FAILED 或 UPDATE\_FAILED 状态，并附带说明发生了什么。`statusReason` 在高级别，错误可以归类为：权限错误、连接错误、验证错误和服务器端错误。 ### 权限错误 同步配置错误或已过期： + “无法连接到 MCP 服务器，因为来电者凭据已过期。” — 您的创建或更新 API 凭证已过期。您可以使用 UpdateRegistryRecord API 重试。 + “收到来自 GetWorkloadAccessToken API 的异常：”-注册表代表您调用 [GetWorkloadAccessToken](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessToken.html)API。有关具体错误，请参阅详细消息。如果您看到拒绝访问错误，请参阅[同步来自外部来源的记录](registry-sync-records.md)。 + “无法解析凭证提供者 ARN:”-证书提供者 ARN 格式错误。提供通过身份创建的有效[凭证提供者](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html) ARN。 AgentCore + “收到来自 GetResourceOauth2Token API 的异常：”-注册表代表您调用 [GetResourceOauth2Token](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html)API。有关具体错误，请参阅详细消息。如果您看到拒绝访问错误，请参阅[同步来自外部来源的记录](registry-sync-records.md)。 + “无法担任为 MCP 服务器授权提供的 IAM 角色。” — 注册表代表您调用 AssumeRole API。有关预期的 IAM 权限，请参阅[同步来自外部来源的记录](registry-sync-records.md)。例如，您必须拥有`iam:PassRole`权限。 ### 连接错误 无法访问服务器： + “无法从 URL: %s 获取代理卡” — A2A ioException + “MCP 服务器返回了 HTTP” — 来自 MCP 服务器的非 200/202 HTTP 响应。请检查网址是否正确以及是否可以连接 MCP 服务器。 + 如果状态码为 401 或 403，请确认您配置了正确的凭据提供商，并且您的凭据有权连接到 MCP 服务器。要排除故障，请手动获取凭证并直接连接到 MCP 服务器。 + “提供的 URL 解析为非公有 IP 地址”-注册表仅支持连接到公共 IP 地址服务器。 + “连接到 MCP 服务器失败” — IOException/connection 失败 + “MCP 服务器 URL 无效”-格式错误的 URL + “无法初始化 MCP 连接”-初始化请求异常 + “发送初始化通知失败”-通知异常 + “无法从 MCP 服务器列出工具”-异常 tools/list + “MCP 服务器 tools/list 分页超时” — 从 MCP 服务器对工具进行分页时，注册表最多仅支持 30 秒。如果您的 MCP 服务器需要更多时间进行同步，请联系 Amazon 支持人员。 ### 验证错误 服务器已响应，但不支持内容： + “无法解析代理卡片 JSON” — A2A 内容为空或格式不正确 JSON + “代理卡超过最大大小限制” — A2A 响应太大 + “无法解析 MCP 服务器响应 JSON” — MCP 内容为空或格式错误 + “MCP 服务器返回的响应无效：缺少结果” — MCP JSON-RPC 缺少结果 + “MCP 服务器响应超出允许的最大大小” — MCP 响应太大 + “描述符类型 %s 不支持 URL 同步” — 不支持的描述符类型 ### 服务器端错误 + “未知错误”-这是服务器端错误。请稍后重试或联系 Amazon 支持人员寻求帮助。 ## Auto-detection 错误 ### “创建组织范围的注册表要求调用者成为组织范围的注册表的一部分 Amazon 组织。” 创建注册表的账户不是 Amazon 组织的成员（例如，它是一个独立账户）。使用属于您的组织的账户创建注册表。 ### “这个组织没有满足Auto-detection 先决条件。” 该组织尚未满足自动检测的先决条件，或者它们尚未完成传播。确认已启用可信访问以进行自动检测，并且您正在使用管理账户或注册的委派管理员创建注册表，然后稍等片刻后重试。请参阅在[整个组织中启用自动检测](registry-organizations.md#registry-organizations-enabling)。 ### “此账户已存在组织范围的注册表。” 此账户已经拥有组织范围的注册表，并且一个账户只能拥有一个。使用现有的注册表，或者在创建另一个注册表之前将其删除。如果您在此账户中找不到注册表，请参阅[查找现有组织范围](#registry-troubleshooting-auto-detection-find-existing)的注册表。 ### “该组织已经存在另一个组织范围的具有主动自动检测功能的注册表。” 您组织中的另一个账户已经拥有一个组织范围的注册表，该注册表具有主动自动检测功能，而一个组织一次只能拥有一个。出于安全考虑，错误消息未命名拥有现有注册表的帐户。要找到它并选择如何解决冲突，请参阅[查找现有组织范围](#registry-troubleshooting-auto-detection-find-existing)的注册表。 ### 查找现有组织范围的注册表 当`CreateRegistry`报告说组织范围的注册表已经存在（无论是在您的账户中还是在组织中的其他地方）时，错误并未命名特定的注册表或拥有该注册表的账户。首先找到现有的注册表，然后决定如何解决冲突。 组织范围的注册表通常由以下账户之一拥有： + 组织的**管理账户**。 + 当前注册为 A Amazon gent Regi **stry 的委派管理员**的账户。 请有权访问这些账户的管理员列出与失败呼叫相同的地区的注册表，然后寻找一个注册机构：`autoDetectionConfiguration.scope``ORGANIZATION` ``` aws agent-registry-control list-registries --region us-east-1 ``` 在管理账号中，确认当前哪个账户是委派的管理员： ``` aws organizations list-delegated-administrators \ --service-principal agent-registry.amazonaws.com ``` 冲突仅适用于同一区域——中的注册表`us-east-1`并不妨碍在中创建注册表`us-west-2`。 找到现有注册表后，请选择以下路径之一： + **共享并重复使用。**让拥有者的账户使用 Amazon RAM 向你的账户授予访问权限，并管理共享注册表中的记录，而不是创建新的注册表。请参阅[使用 Amazon RAM 跨账户共享注册表](registry-cross-account-sharing.md)。 + **在不删除的情况下释放插槽。**现有注册表`false`上的所有者帐户设置为`autoDetectionConfiguration.enabled`；更新生效后，重`CreateRegistry`试。请参见在[注册表上禁用自动检测。](registry-organizations.md#registry-organizations-disable) + **删除现有注册表。**如果不再需要它，则拥有该账户的账号会将其删除。有关拆解顺序，请参阅[关闭自动检测](registry-organizations.md#registry-organizations-turning-off)。 ### `CreateRegistry`即使启用了可信访问权限并注册了委派的管理员，也会失败 确认管理账户具有 Amazon 代理注册表服务相关角色（`AWSServiceRoleForAgentRegistry`）。在创建组织范围的注册表之前，它必须存在于管理账户中，即使授权的管理员是创建该注册表的人也是如此。参见[步骤 1：启用可信访问权限并创建服务相关角色](registry-organizations.md#registry-organizations-step1)。 ### 注册表`已准备就绪`，但记录未出现 确认注册表的自动检测状态为`ACTIVE`（使用`get-registry`），并且成员帐户包含支持的资源类型（AgentCore 运行时或网关）。留出时间完成发现 — 首次设置时，先前存在的资源的初始发现最多可能需要 20 分钟。 ### Auto-detection 重新注册委派管理员后，状态仍显示 “注册局的委派管理员账户已注销” *当管理账户注销拥有组织范围注册表的委托管理员时， Amazon Agent Registry 会关闭该注册表的自动检测功能并记录状态原因。`The registry’s delegated administrator account was deregistered.`此状态原因描述了最初禁用自动检测的原因——这是历史记录，当组织状态以后发生变化时不会刷新。* 如果再次注册了委派的管理员，注册表的自动检测不会自动恢复，并且状态原因会继续显示取消注册消息。在以下每种情况下都应如此： + 同一个账号被重新注册为委托管理员。 + 另一个账户注册为委托管理员，包括该账户已经拥有自己的组织范围的注册表，且之前已禁用自动检测。 + 没有注册新的委派管理员，并且管理账户直接拥有组织范围的注册表。 要恢复自动检测，拥有受影响注册表的帐户必须明确设置为`enabled`。`true`在一个组织`ACTIVE`中，每个区域只能`autoDetection.status`设置一个组织范围的注册表，因此，如果有多个注册机构符合条件，请仅对要保持活跃状态的注册表重新启用自动检测。 ``` aws agent-registry-control update-registry \ --registry-id \ --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":true}}' \ --region us-east-1 ``` 有关整个生命周期，请参阅[关闭自动检测](registry-organizations.md#registry-organizations-turning-off)。 ### “启用自动检测后，无法删除注册表。请先禁用自动检测。” 必须先禁用自动检测，然后才能删除组织范围内的注册表。要删除注册表，请按顺序完成以下步骤： 1. 在注册表上禁用自动检测（设置`autoDetectionConfiguration.enabled`为`false`）。 1. 删除所有注册表记录。 1. 删除注册表。 有关更多信息，请参阅在[注册表上禁用自动检测。](registry-organizations.md#registry-organizations-disable)