Software Development
Error Claude Code: Artinya dan Cara Memperbaikinya
Agustus 202612 menit baca
API key di lingkungan Anda menimpa langganan Anda sepenuhnya. Kalau ada key basi atau yang ditolak tersetel, Claude Code memakainya alih-alih login Anda. Buang variabelnya lalu masuk lagi. Perintah status menunjukkan kredensial mana yang sebenarnya dipakai sesi yang sedang jalan, jadi periksa itu sebelum mengubah apa pun.
Percakapannya melebihi jendela konteks dan compaction otomatis tak bisa mengecilkannya. Mulai percakapan baru, atau jalankan compaction dengan instruksi soal apa yang harus disimpan. Memeriksa dulu apa yang memenuhi jendelanya biasanya mengungkap file besar atau keluaran tool yang tak perlu tetap di konteks.
Ini hampir selalu proxy korporat yang menandatangani ulang lalu lintas TLS, bukan masalah keamanan pada Claude Code. Arahkan environment variable NODE_EXTRA_CA_CERTS ke CA bundle organisasi Anda supaya rantai sertifikatnya tervalidasi. Kalau Anda memang di balik proxy, setel HTTPS_PROXY juga.
Kalau pesannya menyebut gagal melanjutkan percakapan, transkripnya rusak atau terhapus dan sesi itu tak bisa dipulihkan — mulai yang baru. Pesan bahwa tidak ada percakapan dengan session ID itu berbeda: ID-nya mungkin salah, atau sesinya sudah melewati periode retensi Anda.
Tidak. Ketik continue dan Claude melanjut dari blok terakhir yang selesai. Ini mencakup sambungan yang putus, komputer yang tertidur, dan aliran yang mandek. Mengulang seluruh pertanyaannya membayar token yang sama dua kali dan membuang keluaran parsial yang sudah Anda punya.
Ringkasan Utama
Hampir setiap error Claude Code jatuh ke salah satu dari enam keluarga: autentikasi, batas pemakaian, konteks, jaringan, sesi, dan tooling. Dua perintah mengenali Anda ada di keluarga mana sebelum mengubah apa pun — subcommand diagnostik untuk instalasi dan settings, serta perintah status untuk kredensial, penyedia, dan proxy yang sebenarnya dipakai sesinya.
Satu jam termahal yang saya hilangkan pada alat ini dihabiskan dengan keyakinan bahwa langganan saya rusak, padahal sebuah environment variable yang disetel berbulan-bulan sebelumnya untuk proyek lain sedang menimpanya. Error-nya bilang API key-nya tidak sah. Ia berkata jujur persis, dan saya membacanya sebagai masalah akun karena saya lupa key itu ada.
Begitulah bentuk kebanyakan masalah di sini: pesannya akurat dan penyebabnya di tempat yang tidak Anda lihat. Tulisan ini mengelompokkan kegagalan umum per keluarga — autentikasi, batas, konteks, jaringan, sesi, dan tooling — menyebut apa arti sebenarnya masing-masing, dan memberi perbaikannya ketimbang saran untuk mencoba lagi.
Diagnosis sebelum menyunting. Subcommand diagnostiknya mencetak keadaan instalasi dan settings, termasuk file settings mana yang berlaku dan bagaimana hasilnya; perintah status mencetak kredensial, penyedia, base URL, dan proxy yang dipakai sesi yang sedang jalan. Bersama-sama keduanya menjawab sebagian besar pertanyaan langsung, dan mengubah sisanya jadi laporan bug yang bisa ditindaklanjuti orang.
claude doctor # installation + settings diagnostics
/status # which credential, provider, base URL and
# proxy this session is actually using
/usage # plan limits and reset times
/context # what is filling the context window
claude --debug # verbose, with an optional category filter
claude --version
# Two flags that remove variables when something misbehaves:
claude --bare # skip auto-discovery of hooks, skills,
# commands, subagents, plugins, MCP
claude --safe-mode # start with all customisations disabledSebuah API key di lingkungan Anda menimpa langganan Anda, secara senyap dan sepenuhnya. Satu fakta itu menjelaskan sebagian besar kebingungan autentikasi, termasuk kasus seseorang yang yakin sudah masuk tapi tetap ditagih sebagai pengguna API. Pesannya presisi begitu Anda tahu apa yang harus dicari.
# "Invalid API key · Fix external API key"
# An ANTHROPIC_API_KEY in your environment OVERRIDES your
# subscription. If you signed in and are still being billed
# as an API user, or a stale key is being rejected:
unset ANTHROPIC_API_KEY
/login
# "Could not resolve authentication method"
# A worker or background process has no credential. Export the
# variable in the environment, not just in an interactive shell.
# "Your organization has disabled API key authentication"
# Policy, not a bug. Use /login instead of a key.
# Check what is actually in force before changing anything:
/statusJangan memperbaiki error autentikasi dengan menambah kredensial lain. Kalau sebuah key ditolak, langkah yang benar adalah membuangnya lalu masuk, bukan menyetel variabel kedua dengan harapan salah satunya jalan. Dua kredensial yang berlaku bersamaan adalah cara Anda berakhir dengan sesi yang berautentikasi berbeda dari sesi di terminal sebelah, yang jauh lebih sulit didiagnosis daripada error aslinya.
Dua keluarga ini terus-menerus tertukar karena keduanya menghentikan pekerjaan dan keduanya menyebut sesuatu yang penuh. Keduanya tak berhubungan: batas pemakaian soal paket Anda dan reset menurut jam, sementara error konteks soal percakapan ini dan diperbaiki dengan mengecilkannya.
Apa yang sebenarnya dikatakan pesannya:
| Keluarga | Artinya, dan apa yang harus dilakukan |
|---|---|
| Batas sesi atau mingguan tercapai | Kuota paket Anda, dengan waktu reset. Tunggu, ganti model, atau tambah usage credits. Claude Code bisa menunggu di sesi yang terbuka lalu melanjut sendiri |
| Saldo kredit terlalu rendah | Hal yang sama sekali berbeda — kredit prabayar di akun termeter. Tambahkan kredit; tidak ada reset untuk ditunggu |
| Prompt terlalu panjang, compaction gagal | Percakapannya melebihi jendela dan tak bisa diringkas. Clear untuk mulai segar, atau compact dengan instruksi untuk menyimpan yang penting |
| Batas konteks tercapai | Jendelanya penuh dan auto-compaction tidak tersedia. Clear adalah perbaikan yang andal; periksa dulu apa yang memenuhinya |
| Model tidak dikenali atau dibatasi | Nama model di config yang tidak ada, atau yang tidak diizinkan organisasi atau paket Anda. Buka pemilih model untuk melihat apa yang benar-benar tersedia |
Jaringan korporat menghasilkan error yang paling terdengar mengkhawatirkan dan biasanya paling mekanis. Kegagalan sertifikat di balik proxy yang menandatangani ulang lalu lintas bukan insiden keamanan, itu CA bundle yang hilang. Permintaan yang timeout di sambungan lambat adalah bawaan yang terlalu rendah untuk jaringan Anda, bukan layanan yang menggantung.
# Timeouts and retries
API_TIMEOUT_MS=600000 # default 10 minutes
CLAUDE_CODE_MAX_RETRIES=10 # lower it for fast failure in CI
BASH_DEFAULT_TIMEOUT_MS=120000
BASH_MAX_TIMEOUT_MS=600000
# TLS through a corporate proxy that re-signs certificates:
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt
# Behind a proxy at all:
export HTTPS_PROXY=http://proxy.internal:8080
# A response that stopped mid-stream — a dropped connection, a
# laptop that slept — is not lost. Type:
continue
# and Claude resumes from the last completed block.Balasan yang berhenti di tengah aliran bukan pekerjaan yang hilang. Ketik continue dan Claude melanjut dari blok terakhir yang selesai — itu mencakup sambungan yang putus, laptop yang tertidur, dan aliran yang sekadar mandek. Orang rutin mengulang seluruh pertanyaannya, yang membayar token yang sama dua kali dan kehilangan keluaran parsialnya.
Error sesi bersifat spesifik dan masing-masing berarti hal berbeda, yang layak diketahui karena hanya satu yang sungguh tak terpulihkan:
Auto mode punya keluarga error-nya sendiri karena ia melibatkan model kedua. Ketika classifier-nya kena rate limit atau kelebihan beban, ia bilang begitu lalu jatuh ke bertanya pada Anda setelah kegagalan berulang. Ketika percakapannya terlalu besar untuk classifier-nya, compaction memperbaikinya. Dan ketika classifier-nya tak bisa mem-parse hasilnya sendiri, ia memblokir aksinya ketimbang menebak — pertukaran yang benar, meski terbaca seperti kerusakan.
Kegagalan MCP biasanya lebih sederhana dari kelihatannya. Server yang gagal start muncul di tab Errors plugin, umumnya dengan eksekutabel yang hilang, karena biner language server atau tool harus dipasang terpisah dari plugin yang mengonfigurasinya. Subagent yang akan mulai tanpa tool sama sekali ditolak langsung ketimbang dibiarkan gagal belakangan.
Sebagian kegagalan datang dari hulu, dan tandanya ia muncul tiba-tiba di semua yang Anda jalankan ketimbang di satu proyek. Respons kelebihan beban yang berulang berarti layanannya sedang penuh, dan kode lima ratus berarti kegagalan di sisi server. Cek halaman status sebelum melangkah lebih jauh, karena alternatifnya adalah menghabiskan satu jam membelah konfigurasi yang tak pernah berubah.
Untuk CI, setel dua variabel dengan sengaja. Menurunkan jumlah percobaan ulang membuat pipeline gagal cepat ketimbang duduk melewati back-off panjang, yang biasanya Anda inginkan ketika tak ada manusia yang menonton. Menaikkan timeout permintaan adalah pertukaran sebaliknya, dan tepat di jaringan lambat atau yang banyak di-proxy. Kedua bawaannya dipilih untuk sesi interaktif, bukan untuk build agent.
Baca pesannya secara harfiah, lalu periksa dengan apa sesinya benar-benar dikonfigurasi ketimbang apa yang Anda yakini — dua hal itu jauh lebih sering berselisih daripada alat atau jaringannya benar-benar rusak. Simpan perintah diagnostik dan status di memori otot, simpan flag penelusuran masalah untuk saat konfigurasi jadi tersangka, dan cek halaman status sebelum mengira semuanya salah Anda.
Sumber & bacaan lanjutan