View a markdown version of this page

Pemecahan Masalah - Batuan Dasar Amazon AgentCore
Kesalahan validasi skemaRekam kesalahan sinkronisasi

Pemecahan Masalah

Migrasi namespace yang akan datang

AWS Agent Registry saat ini dalam pratinjau publik di bawah namespace bedrock-agentcore. Mulai 6 Agustus 2026, layanan pindah ke namespace agen-registri. Jika Anda menggunakan AWS Agen Registri, Anda harus memperbarui titik akhir, kebijakan IAM, klien SDK, skrip CLI, dan data registri. Untuk informasi selengkapnya tentang migrasi dari pratinjau publik, lihat Panduan migrasi registri komprehensif.

Kesalahan validasi skema

Saat membuat berbagai jenis catatan, Anda mungkin melihat pengecualian validasi untuk deskriptor. Lihat bagian Jenis rekaman yang didukung untuk skema yang valid.

Kesalahan umum:

  • “Versi skema '0.3.0' tidak didukung untuk tipe deskriptor 'a2a'.” — Nilai bidang SchemaVersion seharusnya 0.3 bukan. 0.3.0 Ini sejalan dengan deskripsi versi protokol A2A resmi: “Gunakan versi minor terbaru yang didukung per versi utama”.

  • “Validasi skema gagal: konten tidak sesuai dengan versi skema '0.3' untuk tipe deskriptor 'a2a'.” — Anda dapat menemukan skema pada jenis rekaman yang didukung. Perhatikan bahwa konten akan divalidasi terhadap #/ definitions/AgentCard dalam skema json.

Rekam kesalahan sinkronisasi

Saat Anda membuat atau memperbarui rekaman menggunakan fitur sinkronisasi, catatan dapat bertransisi ke status CREATE_FAILED atau UPDATE_FAILED, dengan menjelaskan apa yang terjadi. statusReason

Pada tingkat tinggi, kesalahan dapat dikategorikan sebagai: kesalahan izin, kesalahan koneksi, kesalahan validasi, dan kesalahan sisi server.

Kesalahan izin

Konfigurasi sinkronisasi salah atau kedaluwarsa:

  • “Tidak dapat terhubung ke server MCP karena kredensyal pemanggil telah kedaluwarsa.” — penelepon buat atau perbarui API telah kedaluwarsa kredensyal. Anda dapat mencoba lagi dengan UpdateRegistryRecord API lagi.

  • “Menerima pengecualian dari GetWorkloadAccessToken API:<detailed message>" — registri memanggil GetWorkloadAccessTokenAPI on-behalf-of the caller. Lihat pesan terperinci untuk mempelajari tentang kesalahan tersebut. Lihat Sinkronisasi catatan dari sumber eksternal jika Anda melihat akses ditolak pengecualian.

  • “Tidak dapat mengurai penyedia kredensi ARN:<arn>" — penyedia kredensyal yang salah format ARN. Ini harus menjadi penyedia kredensi yang valid ARN yang dibuat AgentCore dari Identity.

  • “Menerima pengecualian dari GetResourceOauth2Token API:<detailed message>" — registri memanggil GetResourceOauth2TokenAPI on-behalf-of the caller. Lihat pesan terperinci untuk mempelajari tentang kesalahan tersebut. Lihat Sinkronisasi catatan dari sumber eksternal jika Anda melihat akses ditolak pengecualian.

  • “Tidak dapat mengambil peran IAM yang disediakan untuk otorisasi server MCP.” — registri memanggil AssumeRole API on-behalf-dari penelepon. Lihat Sinkronisasi catatan dari sumber eksternal untuk izin IAM yang diharapkan, misalnya pemanggil harus memiliki izin. iam:PassRole

Kesalahan koneksi

Tidak dapat mencapai server:

  • “Gagal mengambil kartu agen dari URL: %s” — A2A IOException

  • “Server MCP mengembalikan HTTP<code>" - respons 200/202 non-HTTP dari server MCP. Silakan periksa apakah URL sudah benar dan server MCP dapat dihubungkan.

  • “URL yang disediakan diselesaikan ke alamat IP non-publik” - Registry hanya mendukung koneksi ke server alamat IP publik.

  • “Gagal terhubung ke server MCP” - IOException/connection kegagalan

  • “URL server MCP tidak valid” - URL cacat

  • “Gagal menginisialisasi koneksi MCP” - inisialisasi pengecualian permintaan

  • “Gagal mengirim pemberitahuan yang diinisialisasi” - pengecualian pemberitahuan

  • “Gagal membuat daftar alat dari server MCP” - pengecualian tools/list

  • “Waktu tools/list pagination server MCP habis” - registri hanya mendukung paling banyak 30 detik saat alat paginasi dari server MCP. Hubungi AWS dukungan jika server MCP Anda membutuhkan lebih banyak waktu untuk sinkronisasi.

Kesalahan validasi

Server merespons tetapi konten tidak didukung:

  • “Gagal mengurai kartu agen JSON” - Konten A2A kosong atau cacat JSON

  • “Kartu agen melebihi batas ukuran maksimum” — respons A2A terlalu besar

  • “Gagal mengurai respons server MCP JSON” - konten MCP kosong atau cacat

  • “Server MCP mengembalikan respons yang tidak valid: hasil hilang” - MCP hasil hilang JSON-RPC

  • “Respons server MCP melebihi ukuran maksimum yang diizinkan” - respons MCP terlalu besar

  • “Tipe deskriptor %s tidak mendukung sinkronisasi URL” — tipe deskriptor tidak didukung

Kesalahan sisi server

  • “Kesalahan tidak diketahui” - Ini adalah kesalahan sisi server. Silakan coba lagi nanti atau hubungi AWS dukungan untuk bantuan.