# 问题排查
<a name="registry-troubleshooting"></a>

**即将进行的命名空间迁移**  
 AWS Agent Registry 目前在 bedrock-agentcore 命名空间下处于公开预览状态。从 2026 年 8 月 6 日起，该服务将移至代理注册表命名空间。如果您使用 AWS 代理注册表，则必须更新您的终端节点、IAM 策略、SDK 客户端、CLI 脚本和注册表数据。有关从公共预览版迁移的更多信息，请参阅[注册表迁移综合指南](registry-faq.md)。

## 架构验证错误
<a name="registry-troubleshooting-schema-validation"></a>

创建不同类型的记录时，您可能会看到描述符的验证异常。有关有效的架构，请参阅[支持的记录类型](registry-supported-record-types.md)部分。

常见错误：
+ “描述符类型'a2a'不支持架构版本'0.3.0'。” — SchemaVersion 字段值应`0.3`改为。`0.3.0`这与 [A2A 协议的官方版本描述](https://a2a-protocol.org/latest/specification/#446-agentinterface)一致：“每个主要版本都使用最新支持的次要版本”。
+ “架构验证失败：内容不符合描述符类型'a2a'的架构版本'0.3'。” — 您可以在 “[支持的记录类型](registry-supported-record-types.md)” 上找到架构。请注意，内容将根据 json 架构definitions/AgentCard 中的 \#/进行验证。

## 记录同步错误
<a name="registry-troubleshooting-sync-errors"></a>

当您使用同步功能创建或更新记录时，记录可能会转换为 CREATE\_FAILED 或 UPDATE\_FAILED 状态，并附上对发生的事情进行解释。`statusReason`

在高级别，错误可以归类为：权限错误、连接错误、验证错误和服务器端错误。

### 权限错误
<a name="registry-troubleshooting-sync-permission"></a>

同步配置错误或已过期：
+ “无法连接到 MCP 服务器，因为来电者凭据已过期。” — 创建或更新 API 的调用者凭证已过期。您可以再次使用 UpdateRegistryRecord API 重试。
+ “收到来自 GetWorkloadAccessToken API 的异常：<detailed message>” — 注册表代表调用方调用 [GetWorkloadAccessToken](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessToken.html)API。请参阅详细消息以了解错误。如果您看到访问被拒绝异常，请参阅[同步来自外部来源的记录](registry-sync-records.md)。
+ “无法解析凭证提供者 ARN:<arn>” — 格式错误的凭证提供者 ARN。这必须是通过 Identit [y 创建的有效凭证提供者](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html) ARN。 AgentCore 
+ “收到来自 GetResourceOauth2Token API 的异常：<detailed message>” — 注册表代表调用方调用 [GetResourceOauth2Token](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html)API。请参阅详细消息以了解错误。如果您看到访问被拒绝异常，请参阅[同步来自外部来源的记录](registry-sync-records.md)。
+ “无法担任为 MCP 服务器授权提供的 IAM 角色。” — 注册表代表调用方调用 AssumeRole API。有关预期的 IAM 权限，请参阅[同步来自外部来源的记录](registry-sync-records.md)，例如来电者必须拥有`iam:PassRole`权限。

### 连接错误
<a name="registry-troubleshooting-sync-connection"></a>

无法访问服务器：
+ “无法从 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 支持人员。

### 验证错误
<a name="registry-troubleshooting-sync-validation"></a>

服务器已响应，但不支持内容：
+ “无法解析代理卡片 JSON” — A2A 内容为空或格式不正确 JSON
+ “代理卡超过最大大小限制” — A2A 响应太大
+ “无法解析 MCP 服务器响应 JSON” — MCP 内容为空或格式错误
+ “MCP 服务器返回的响应无效：缺少结果” — MCP JSON-RPC 缺少结果
+ “MCP 服务器响应超出允许的最大大小” — MCP 响应太大
+ “描述符类型 %s 不支持 URL 同步” — 不支持的描述符类型

### 服务器端错误
<a name="registry-troubleshooting-sync-server"></a>
+ “未知错误”-这是服务器端错误。请稍后重试或联系 AWS 支持人员寻求帮助。