# 疑難排解
<a name="registry-troubleshooting"></a>

**即將進行的命名空間遷移**  
 AWS 客服人員登錄檔目前在 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>" — 註冊機構on-behalf-of發起人呼叫 [GetWorkloadAccessToken](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetWorkloadAccessToken.html) API。請參閱詳細訊息以了解錯誤。如果您看到存取遭拒的例外狀況，請參閱[同步來自外部來源的記錄](registry-sync-records.md)。
+ 「無法剖析登入資料提供者 ARN：<arn>」 — 格式錯誤的登入資料提供者 ARN。這必須是從 AgentCore Identity 建立的有效[登入資料提供者](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-outbound-credential-provider.html) ARN。
+ 「GetResourceOauth2Token API 收到例外狀況：<detailed message>" — 註冊機構on-behalf-of發起人呼叫 [GetResourceOauth2Token](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_GetResourceOauth2Token.html) API。請參閱詳細訊息以了解錯誤。如果您看到存取遭拒的例外狀況，請參閱[同步來自外部來源的記錄](registry-sync-records.md)。
+ 「無法擔任 MCP 伺服器授權提供的 IAM 角色。」 — 登錄代表發起 on-behalf-of 人呼叫 AssumeRole API。請參閱[從外部來源同步記錄](registry-sync-records.md)以取得預期的 IAM 許可，例如呼叫者必須具有`iam:PassRole`許可。

### 連線錯誤
<a name="registry-troubleshooting-sync-connection"></a>

無法連線到伺服器：
+ 「無法從 URL 擷取客服人員卡：%s」 — A2A IOException
+ 「MCP 伺服器傳回 HTTP <code>」 — 來自 MCP 伺服器的非 200/202 HTTP 回應。請檢查 URL 是否正確，以及是否可以連接 MCP 伺服器。
+ 「提供的 URL 解析為非公有 IP 地址」 — 登錄檔僅支援連線至公有 IP 地址伺服器。
+ 「無法連線至 MCP 伺服器」 — IOException/連線失敗
+ 「無效的 MCP 伺服器 URL」 — 格式錯誤的 URL
+ 「無法初始化 MCP 連線」—初始化請求例外狀況
+ 「無法傳送初始化通知」 — 通知例外狀況
+ 「無法從 MCP 伺服器列出工具」—工具/清單例外狀況
+ 「MCP 伺服器工具/清單分頁逾時」 — 從 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>
+ "Unknown error" — 這是伺服器端錯誤。請稍後重試，或聯絡 AWS Support 尋求協助。