问题排查
即将进行的命名空间迁移
AWS Agent Registry 目前在 bedrock-agentcore 命名空间下处于公开预览状态。从 2026 年 8 月 6 日起，该服务将移至代理注册表命名空间。如果您使用 AWS 代理注册表，则必须更新您的终端节点、IAM 策略、SDK 客户端、CLI 脚本和注册表数据。有关从公共预览版迁移的更多信息，请参阅注册表迁移综合指南。
架构验证错误
创建不同类型的记录时，您可能会看到描述符的验证异常。有关有效的架构，请参阅支持的记录类型部分。
常见错误：
-
“描述符类型'a2a'不支持架构版本'0.3.0'。” — SchemaVersion 字段值应
0.3改为。0.3.0这与 A2A 协议的官方版本描述一致：“每个主要版本都使用最新支持的次要版本”。 -
“架构验证失败：内容不符合描述符类型'a2a'的架构版本'0.3'。” — 您可以在 “支持的记录类型” 上找到架构。请注意，内容将根据 json 架构definitions/AgentCard 中的 #/进行验证。
记录同步错误
当您使用同步功能创建或更新记录时，记录可能会转换为 CREATE_FAILED 或 UPDATE_FAILED 状态，并附上对发生的事情进行解释。statusReason
在高级别，错误可以归类为：权限错误、连接错误、验证错误和服务器端错误。
权限错误
同步配置错误或已过期：
-
“无法连接到 MCP 服务器，因为来电者凭据已过期。” — 创建或更新 API 的调用者凭证已过期。您可以再次使用 UpdateRegistryRecord API 重试。
-
“收到来自 GetWorkloadAccessToken API 的异常：<detailed message>” — 注册表代表调用方调用 GetWorkloadAccessTokenAPI。请参阅详细消息以了解错误。如果您看到访问被拒绝异常，请参阅同步来自外部来源的记录。
-
“无法解析凭证提供者 ARN:<arn>” — 格式错误的凭证提供者 ARN。这必须是通过 Identit y 创建的有效凭证提供者 ARN。 AgentCore
-
“收到来自 GetResourceOauth2Token API 的异常：<detailed message>” — 注册表代表调用方调用 GetResourceOauth2TokenAPI。请参阅详细消息以了解错误。如果您看到访问被拒绝异常，请参阅同步来自外部来源的记录。
-
“无法担任为 MCP 服务器授权提供的 IAM 角色。” — 注册表代表调用方调用 AssumeRole API。有关预期的 IAM 权限，请参阅同步来自外部来源的记录，例如来电者必须拥有
iam:PassRole权限。
连接错误
无法访问服务器：
-
“无法从 URL: %s 获取代理卡” — A2A ioException
-
“MCP 服务器返回了 HTTP<code>” — 来自 MCP 服务器的非 200/202 HTTP 响应。请检查网址是否正确以及是否可以连接 MCP 服务器。
-
“提供的 URL 解析为非公共 IP 地址”-注册表仅支持连接到公共 IP 地址服务器。
-
“连接到 MCP 服务器失败” — IOException/connection 失败
-
“MCP 服务器 URL 无效”-格式错误的 URL
-
“无法初始化 MCP 连接”-初始化请求异常
-
“发送初始化通知失败”-通知异常
-
“无法从 MCP 服务器列出工具”-异常 tools/list
-
“MCP 服务器 tools/list 分页超时” — 从 MCP 服务器对工具进行分页时，注册表最多仅支持 30 秒。如果您的 MCP 服务器需要更多时间进行同步，请联系 AWS 支持人员。
验证错误
服务器已响应，但不支持内容：
-
“无法解析代理卡片 JSON” — A2A 内容为空或格式不正确 JSON
-
“代理卡超过最大大小限制” — A2A 响应太大
-
“无法解析 MCP 服务器响应 JSON” — MCP 内容为空或格式错误
-
“MCP 服务器返回的响应无效：缺少结果” — MCP JSON-RPC 缺少结果
-
“MCP 服务器响应超出允许的最大大小” — MCP 响应太大
-
“描述符类型 %s 不支持 URL 同步” — 不支持的描述符类型
服务器端错误
-
“未知错误”-这是服务器端错误。请稍后重试或联系 AWS 支持人员寻求帮助。
