Kode error Spanner

Halaman ini menjelaskan kode error Spanner dan tindakan yang disarankan untuk menangani error ini. Google API, termasuk Spanner, menggunakan kode error kanonis yang ditentukan oleh google.rpc.Code.

Jika permintaan Spanner berhasil, API akan menampilkan kode status HTTP 200 OK beserta data yang diminta dalam isi respons.

Jika permintaan gagal, Spanner API akan menampilkan kode status HTTP 4xx atau 5xx yang secara umum mengidentifikasi kegagalan serta respons yang memberikan informasi lebih spesifik tentang error yang menyebabkan kegagalan.

Objek respons berisi satu kolom error yang nilainya berisi elemen berikut:

Elemen Deskripsi
code Kode status HTTP yang secara umum mengidentifikasi kegagalan permintaan.
message Informasi spesifik tentang kegagalan permintaan.
status Kode error kanonis (google.rpc.Code) untuk Google API. Kode yang dapat ditampilkan oleh Spanner API tercantum dalam Kode error.

Jika permintaan yang dibuat dengan jenis konten application/x-protobuf menghasilkan error, permintaan tersebut akan menampilkan pesan google.rpc.Status serial sebagai payload.

Kode error

Cara yang direkomendasikan untuk mengklasifikasikan error adalah dengan memeriksa nilai kode error kanonis (google.rpc.Code). Dalam error JSON, kode ini muncul di kolom status. Pada error application/x-protobuf, error tersebut ada di kolom code.

Kode error Deskripsi Tindakan yang disarankan
ABORTED Operasi dibatalkan, umumnya karena masalah konkurensi seperti kegagalan pemeriksaan pengurut atau pembatalan transaksi. Menunjukkan bahwa permintaan bertentangan dengan permintaan lain.

Untuk mengetahui informasi selengkapnya tentang error Database schema has changed, lihat Error skema database telah berubah.		 Untuk commit non-transaksional:
Coba lagi permintaan atau susun entitas Anda untuk mengurangi pertentangan.

Untuk permintaan yang merupakan bagian dari commit transaksional:
Coba lagi seluruh transaksi atau susun entitas Anda untuk mengurangi pertentangan.
ALREADY_EXISTS Entitas yang coba dibuat oleh klien sudah ada (misalnya, menyisipkan baris dengan kunci utama yang sudah ada). Jangan mencoba lagi tanpa memperbaiki masalah.
CANCELLED Operasi dibatalkan, biasanya oleh pemanggil. Coba lagi operasi tersebut.
DEADLINE_EXCEEDED Batas waktu berakhir sebelum operasi selesai. Selidiki apakah batas waktunya cukup. Gunakan batas waktu yang sesuai dengan waktu sebenarnya saat respons berguna. Perhatikan bahwa untuk operasi yang mengubah status sistem, error mungkin ditampilkan meskipun operasi telah berhasil diselesaikan.

Untuk mengetahui tipsnya, lihat Memecahkan masalah error batas waktu terlampaui.
FAILED_PRECONDITION Operasi ditolak karena prasyarat untuk permintaan tidak terpenuhi. Kolom pesan dalam respons error memberikan informasi tentang prasyarat yang gagal. Misalnya, membaca atau membuat kueri dari stempel waktu yang telah melampaui keusangan stempel waktu maksimum. Jangan mencoba lagi tanpa memperbaiki masalah.
INTERNAL Server menampilkan error. Beberapa invarian yang diperlukan oleh sistem pokok telah rusak. Jangan coba lagi kecuali Anda memahami situasi dan penyebab spesifik error tersebut.
INVALID_ARGUMENT Klien menentukan nilai yang tidak valid. Kolom pesan dalam respons error memberikan informasi tentang nilai mana yang tidak valid. Jangan mencoba lagi tanpa memperbaiki masalah.
NOT_FOUND Menunjukkan bahwa beberapa entity yang diminta, seperti memperbarui entity atau membuat kueri tabel atau kolom, tidak ada. Jangan mencoba lagi tanpa memperbaiki masalah.
OUT_OF_RANGE Upaya operasi dilakukan melampaui rentang yang valid. Jangan coba lagi tanpa memperbaiki masalah.
PERMISSION_DENIED Pengguna tidak diizinkan untuk membuat permintaan. Jangan mencoba lagi tanpa memperbaiki masalah.
RESOURCE_EXHAUSTED Beberapa resource telah habis.

Untuk bidang administrator, kemungkinan project melampaui kuota atau seluruh sistem file kehabisan ruang.

Untuk bidang data, hal ini dapat terjadi jika node Spanner Anda kelebihan beban.

Untuk mengetahui informasi selengkapnya, lihat juga Kode error terkait sesi.		 Untuk bidang administrator, pastikan Anda tidak melebihi kuota Spanner atau project. Jika Anda telah melampaui kuota, minta penambahan kuota atau tunggu hingga kuota direset sebelum mencoba lagi. Konfigurasi percobaan ulang Anda untuk menggunakan backoff eksponensial.

Untuk bidang data, pastikan node Spanner Anda tidak melebihi kapasitasnya. Spanner mencoba ulang error ini di library klien. Jika semua percobaan ulang gagal, lihat Error mekanisme kontrol alur.

Secara umum, jika aplikasi Anda mengalami error RESOURCE_EXHAUSTED, perlakukan situasi ini seperti error UNAVAILABLE, dan coba lagi dengan backoff eksponensial.
UNAUTHENTICATED Permintaan tidak memiliki kredensial autentikasi yang valid untuk operasi. Jangan coba lagi tanpa memperbaiki masalah.
UNAVAILABLE Server tidak tersedia. Coba lagi menggunakan backoff eksponensial. Perlu diketahui bahwa mencoba kembali operasi non-idempoten tidak selalu aman.
UNIMPLEMENTED Operasi tidak diterapkan atau tidak didukung/diaktifkan dalam layanan ini. Jangan coba lagi tanpa memperbaiki masalah.
UNKNOWN Server menampilkan error yang tidak diketahui. Error yang dilaporkan oleh API yang tidak menampilkan informasi error yang mencukupi dapat dianggap sebagai error ini. Pastikan permintaan Anda aman. Kemudian, coba lagi dengan backoff eksponensial.

Error skema database telah berubah

Anda mungkin melihat error ABORTED dengan pesan yang mirip dengan salah satu pesan berikut:

  • Database schema has changed
  • Transaction aborted. Database schema probably changed during transaction, retry may succeed.

Error ini biasanya terjadi saat pembaruan skema membatalkan transaksi. Namun, alasan lain juga dapat memicunya tanpa pembaruan skema eksplisit. Misalnya, status internal sementara, seperti skema klien yang tidak berlaku selama commit transaksi, dapat memicu error ini.

Seperti error ABORTED lainnya, tangani error ini dengan mencoba ulang seluruh transaksi.

Error sesi

Spanner menggunakan sesi untuk mengelola interaksi antara aplikasi dan database Anda. Sesi merepresentasikan koneksi ke database dan memfasilitasi operasi seperti baca dan tulis.

Error terkait sesi umum yang mungkin dialami aplikasi Anda meliputi:

Sesi tidak ditemukan

Error Session not found terjadi saat aplikasi Anda mencoba menggunakan sesi yang tidak ada lagi. Hal ini dapat terjadi karena beberapa alasan.

  • Aplikasi klien Anda dapat menghapus sesi secara eksplisit. Misalnya, menutup klien database dalam kode Anda atau memanggil deleteSessions API secara langsung akan menghapus sesi. Jika Anda tidak menggunakan salah satu library klien Spanner, buat sesi baru saat error ini terjadi. Tambahkan sesi baru ke kumpulan sesi Anda dan hapus sesi yang dihapus dari kumpulan tersebut.

  • Spanner juga otomatis menghapus sesi dalam kondisi tertentu.

    • Sesi akan dihapus jika tetap tidak ada aktivitas selama lebih dari satu jam. Hal ini dapat terjadi dalam tugas aliran data saat pemrosesan downstream membutuhkan waktu lebih lama daripada waktu tunggu tidak ada aktivitas sesi. Jika Anda menggunakan tugas Dataflow, tambahkan operasi transformasi Reshuffle setelah pembacaan Spanner di pipeline Dataflow. Hal ini dapat membantu memisahkan operasi baca Spanner dari langkah-langkah pemrosesan berjalan lama berikutnya.

    • Spanner juga menghapus sesi jika sudah lebih dari 28 hari. Jika Anda menggunakan library klien, library ini akan menangani kasus ini secara otomatis. Jika Anda tidak menggunakan salah satu library klien Spanner, buat sesi baru saat error ini terjadi. Tambahkan sesi baru ke kumpulan sesi Anda dan hapus sesi yang dihapus dari kumpulan.

  • Jika Anda menggunakan salah satu library klien Spanner, maka library akan mengelola sesi secara otomatis. Jika Anda mengalami error ini, pastikan kode Anda tidak menghapus sesi secara eksplisit, seperti dengan menutup klien database. Terkadang, hal ini juga dapat disebabkan oleh masalah dalam pengelolaan sesi library klien.

Resource sudah terlampaui

Error RESOURCE_EXHAUSTED: No session available in the pool atau RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session menunjukkan bahwa aplikasi Anda tidak dapat memperoleh sesi dari pool sesi. Hal ini terjadi saat tidak ada sesi yang tersedia untuk memproses permintaan baca atau tulis baru.

Tabel berikut menjelaskan beberapa alasan yang dapat menyebabkan error ini, dan tindakan yang direkomendasikan.

Alasan Tindakan yang disarankan
Semua sesi dalam kumpulan sedang digunakan. Aplikasi Anda mungkin menerima lebih banyak permintaan serentak daripada jumlah maksimum sesi yang dikonfigurasi. Semua sesi di pool sudah digunakan, dan tidak ada sesi yang tersedia untuk permintaan baru. Aktifkan sesi yang di-multiplex. Sesi yang di-multiplex memungkinkan beberapa transaksi dan pembacaan untuk berbagi satu sesi, yang dapat mengurangi jumlah total sesi yang diperlukan oleh aplikasi Anda. Anda juga dapat meningkatkan konfigurasi maxSession atau minSession di setelan kumpulan sesi.
Permintaan memerlukan waktu yang lama untuk diselesaikan. Permintaan baca atau tulis yang berjalan lama dapat menggunakan semua sesi yang tersedia dalam jangka waktu yang lama. Jika permintaan ini membutuhkan waktu lebih lama daripada setelan waktu tunggu perolehan sesi, permintaan baru tidak dapat memperoleh sesi dari kumpulan sesi. Selidiki mengapa permintaan Anda memerlukan waktu lama untuk diselesaikan. Optimalkan kueri atau logika aplikasi Anda untuk mengurangi waktu eksekusi. Anda dapat meningkatkan setelan waktu tunggu perolehan sesi. Anda juga dapat mengaktifkan sesi yang di-multiplex untuk library klien yang memenuhi syarat guna meningkatkan pemanfaatan sesi.
Terdapat kebocoran sesi. Kebocoran sesi terjadi saat aplikasi Anda mengeluarkan sesi dari pool, tetapi tidak mengembalikannya setelah menyelesaikan permintaan. Hal ini biasanya terjadi saat iterator atau kumpulan hasil tidak ditutup dengan benar dalam kode Anda. Jika semua sesi bocor, tidak ada sesi yang tersedia untuk permintaan baru. Debug kode aplikasi Anda untuk mengidentifikasi dan memperbaiki kebocoran sesi. Pastikan kode Anda menutup semua iterator dan set hasil dengan benar. Untuk mengetahui informasi selengkapnya, lihat Solusi deteksi kebocoran sesi. Anda juga dapat menggunakan fitur pembersihan otomatis kebocoran sesi untuk menyetel kumpulan sesi agar otomatis menyelesaikan transaksi yang tidak aktif.
Pembuatan sesi lambat. Pembuatan sesi adalah operasi yang mahal secara komputasi. Library klien mengirimkan API BatchCreateSessions untuk membuat sesi awal (berdasarkan konfigurasi minSession) dan API CreateSessions untuk sesi tambahan (hingga maxSession). Jika pembuatan sesi membutuhkan waktu lebih lama daripada setelan waktu tunggu habis perolehan sesi, permintaan baru mungkin akan mengalami waktu tunggu habis saat menunggu sesi. Verifikasi latensi panggilan API BatchCreateSessions dan CreateSessions. Pembuatan sesi yang lambat mungkin diakibatkan oleh masalah resource di sisi Spanner atau sejumlah besar operasi pembuatan sesi serentak.

Error mekanisme kontrol alur

Spanner dapat mengaktifkan mekanisme kontrol alurnya untuk melindungi dirinya dari kelebihan beban dalam kondisi berikut:

  • Penggunaan CPU tinggi pada node Spanner. Jika Anda menduga bahwa permintaan Anda menyebabkan penggunaan CPU yang tinggi, Anda dapat menggunakan metrik penggunaan CPU untuk menyelidiki masalah tersebut.
  • Mungkin ada hotspot, yang meningkatkan waktu pemrosesan permintaan. Jika Anda menduga bahwa permintaan Anda menyebabkan hotspot, lihat Menemukan hotspot di database Anda untuk menyelidiki masalah ini. Untuk mengetahui informasi selengkapnya, lihat Key Visualizer.

Mekanisme kontrol alur didukung oleh library klien berikut:

Waktu keseluruhan untuk menyelesaikan permintaan tidak akan bertambah karena penggunaan mekanisme kontrol alur. Tanpa mekanisme ini, Spanner akan menunggu sebelum memproses permintaan dan akhirnya menampilkan error DEADLINE_EXCEEDED.

Saat mekanisme kontrol alur aktif, Spanner akan mengirimkan permintaan kembali ke klien untuk dicoba lagi. Jika percobaan ulang menggunakan seluruh batas waktu yang diberikan pengguna, klien akan menerima error RESOURCE_EXHAUSTED. Error ini ditampilkan jika Spanner memperkirakan waktu pemrosesan permintaan terlalu lama. Error ini menyebarkan kontrol alur dan Spanner mencoba lagi permintaan ke klien, bukan mengakumulasikan percobaan ulang secara internal. Hal ini memungkinkan Spanner menghindari akumulasi konsumsi resource tambahan.