疑難排解
即將進行的命名空間遷移
AWS 客服人員登錄檔目前在 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>" — 註冊機構on-behalf-of發起人呼叫 GetWorkloadAccessToken API。請參閱詳細訊息以了解錯誤。如果您看到存取遭拒的例外狀況，請參閱同步來自外部來源的記錄。
-
「無法剖析登入資料提供者 ARN：<arn>」 — 格式錯誤的登入資料提供者 ARN。這必須是從 AgentCore Identity 建立的有效登入資料提供者 ARN。
-
「GetResourceOauth2Token API 收到例外狀況：<detailed message>" — 註冊機構on-behalf-of發起人呼叫 GetResourceOauth2Token API。請參閱詳細訊息以了解錯誤。如果您看到存取遭拒的例外狀況，請參閱同步來自外部來源的記錄。
-
「無法擔任 MCP 伺服器授權提供的 IAM 角色。」 — 登錄代表發起 on-behalf-of 人呼叫 AssumeRole API。請參閱從外部來源同步記錄以取得預期的 IAM 許可，例如呼叫者必須具有
iam:PassRole許可。
連線錯誤
無法連線到伺服器：
-
「無法從 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 支援。
驗證錯誤
伺服器已回應，但不支援內容：
-
「無法剖析客服人員卡 JSON」 — A2A 內容空白或格式不正確的 JSON
-
「代理程式卡超過大小上限」 — A2A 回應過大
-
「無法剖析 MCP 伺服器回應 JSON」—MCP 內容空白或格式錯誤
-
「MCP 伺服器傳回無效的回應：缺少結果」 — MCP JSON-RPC 缺少結果
-
「MCP 伺服器回應超過允許的大小上限」 — MCP 回應過大
-
「描述項類型 %s 不支援 URL 同步」 — 不支援的描述項類型
伺服器端錯誤
-
"Unknown error" — 這是伺服器端錯誤。請稍後重試，或聯絡 AWS Support 尋求協助。
