Pemecahan Masalah

​

Masalah instalasi umum

​

Masalah instalasi Windows: kesalahan di WSL

Anda mungkin mengalami masalah berikut di WSL:

Masalah deteksi OS/platform: Jika Anda menerima kesalahan selama instalasi, WSL mungkin menggunakan npm Windows. Coba:

• Jalankan npm config set os linux sebelum instalasi
• Instal dengan npm install -g @anthropic-ai/claude-code --force --no-os-check (JANGAN gunakan sudo)

Kesalahan Node tidak ditemukan: Jika Anda melihat exec: node: not found saat menjalankan claude, lingkungan WSL Anda mungkin menggunakan instalasi Node.js Windows. Anda dapat mengonfirmasi ini dengan which npm dan which node, yang seharusnya menunjuk ke jalur Linux yang dimulai dengan /usr/ bukan /mnt/c/. Untuk memperbaiki ini, coba instal Node melalui manajer paket distribusi Linux Anda atau melalui nvm.

Konflik versi nvm: Jika Anda memiliki nvm yang diinstal di WSL dan Windows, Anda mungkin mengalami konflik versi saat beralih versi Node di WSL. Ini terjadi karena WSL mengimpor PATH Windows secara default, menyebabkan nvm/npm Windows mengambil prioritas atas instalasi WSL.

Anda dapat mengidentifikasi masalah ini dengan:

• Menjalankan which npm dan which node - jika mereka menunjuk ke jalur Windows (dimulai dengan /mnt/c/), versi Windows sedang digunakan
• Mengalami fungsionalitas yang rusak setelah beralih versi Node dengan nvm di WSL

Untuk mengatasi masalah ini, perbaiki PATH Linux Anda untuk memastikan versi node/npm Linux mengambil prioritas:

Solusi utama: Pastikan nvm dimuat dengan benar di shell Anda

Penyebab paling umum adalah nvm tidak dimuat di shell non-interaktif. Tambahkan yang berikut ke file konfigurasi shell Anda (~/.bashrc, ~/.zshrc, dll.):

# Muat nvm jika ada
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Atau jalankan langsung di sesi Anda saat ini:

source ~/.nvm/nvm.sh

Alternatif: Sesuaikan urutan PATH

Jika nvm dimuat dengan benar tetapi jalur Windows masih mengambil prioritas, Anda dapat secara eksplisit menambahkan jalur Linux Anda ke PATH di konfigurasi shell Anda:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

​

Masalah instalasi Linux dan Mac: kesalahan izin atau perintah tidak ditemukan

Saat menginstal Claude Code dengan npm, masalah PATH dapat mencegah akses ke claude. Anda juga mungkin mengalami kesalahan izin jika prefix global npm Anda tidak dapat ditulis pengguna (misalnya /usr, atau /usr/local).

​

Solusi yang direkomendasikan: Instalasi Claude Code native

Claude Code memiliki instalasi native yang tidak bergantung pada npm atau Node.js.

Gunakan perintah berikut untuk menjalankan installer native.

macOS, Linux, WSL:

# Instal versi stabil (default)
curl -fsSL https://claude.ai/install.sh | bash

# Instal versi terbaru
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Instal nomor versi tertentu
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Instal versi stabil (default)
irm https://claude.ai/install.ps1 | iex

# Instal versi terbaru
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Instal nomor versi tertentu
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Perintah ini menginstal build Claude Code yang sesuai untuk sistem operasi dan arsitektur Anda dan menambahkan symlink ke instalasi di ~/.local/bin/claude.

​

Solusi alternatif: Migrasi ke instalasi lokal

Alternatifnya, jika Claude Code akan berjalan, Anda dapat bermigrasi ke instalasi lokal:

claude migrate-installer

Ini memindahkan Claude Code ke ~/.claude/local/ dan menyiapkan alias di konfigurasi shell Anda. Tidak diperlukan sudo untuk pembaruan di masa mendatang.

Setelah migrasi, restart shell Anda, lalu verifikasi instalasi Anda:

Di macOS/Linux/WSL:

which claude  # Seharusnya menunjukkan alias ke ~/.claude/local/claude

Di Windows:

where claude  # Seharusnya menunjukkan jalur ke executable claude

Verifikasi instalasi:

claude doctor # Periksa kesehatan instalasi

​

Izin dan autentikasi

​

Prompt izin berulang

Jika Anda terus-menerus menyetujui perintah yang sama, Anda dapat mengizinkan alat tertentu untuk berjalan tanpa persetujuan menggunakan perintah /permissions. Lihat dokumentasi Permissions.

​

Masalah autentikasi

Jika Anda mengalami masalah autentikasi:

1. Jalankan /logout untuk keluar sepenuhnya
2. Tutup Claude Code
3. Restart dengan claude dan selesaikan proses autentikasi lagi

Jika masalah berlanjut, coba:

rm -rf ~/.config/claude-code/auth.json
claude

Ini menghapus informasi autentikasi tersimpan Anda dan memaksa login bersih.

​

Performa dan stabilitas

​

Penggunaan CPU atau memori tinggi

Claude Code dirancang untuk bekerja dengan sebagian besar lingkungan pengembangan, tetapi dapat mengonsumsi sumber daya yang signifikan saat memproses codebase besar. Jika Anda mengalami masalah performa:

1. Gunakan /compact secara teratur untuk mengurangi ukuran konteks
2. Tutup dan restart Claude Code di antara tugas-tugas besar
3. Pertimbangkan untuk menambahkan direktori build besar ke file .gitignore Anda

​

Perintah hang atau freeze

Jika Claude Code tampak tidak responsif:

1. Tekan Ctrl+C untuk mencoba membatalkan operasi saat ini
2. Jika tidak responsif, Anda mungkin perlu menutup terminal dan restart

​

Tombol ESC tidak berfungsi di terminal JetBrains (IntelliJ, PyCharm, dll.)

Jika Anda menggunakan Claude Code di terminal JetBrains dan tombol ESC tidak mengganggu agen seperti yang diharapkan, ini kemungkinan karena bentrokan keybinding dengan shortcut default JetBrains.

Untuk memperbaiki masalah ini:

1. Pergi ke Settings → Tools → Terminal
2. Klik hyperlink “Configure terminal keybindings” di sebelah “Override IDE Shortcuts”
3. Dalam keybinding terminal, gulir ke bawah ke “Switch focus to Editor” dan hapus shortcut tersebut

Ini akan memungkinkan tombol ESC berfungsi dengan benar untuk membatalkan operasi Claude Code alih-alih ditangkap oleh aksi “Switch focus to Editor” PyCharm.

​

Masalah pencarian dan penemuan

Jika alat Search, penyebutan @file, agen kustom, dan perintah slash kustom tidak berfungsi, instal ripgrep sistem:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Kemudian atur USE_BUILTIN_RIPGREP=0 di environment Anda.

​

Hasil pencarian lambat atau tidak lengkap di WSL

Penalti performa baca disk saat bekerja lintas sistem file di WSL dapat menghasilkan kecocokan yang lebih sedikit dari yang diharapkan (tetapi bukan kurangnya fungsionalitas pencarian sepenuhnya) saat menggunakan Claude Code di WSL.

Solusi:

1. Kirim pencarian yang lebih spesifik: Kurangi jumlah file yang dicari dengan menentukan direktori atau jenis file: “Cari logika validasi JWT di paket auth-service” atau “Temukan penggunaan hash md5 di file JS”.

2. Pindahkan proyek ke filesystem Linux: Jika memungkinkan, pastikan proyek Anda berada di filesystem Linux (/home/) bukan filesystem Windows (/mnt/c/).

3. Gunakan Windows native sebagai gantinya: Pertimbangkan menjalankan Claude Code secara native di Windows alih-alih melalui WSL, untuk performa sistem file yang lebih baik.

​

Masalah format markdown

Claude Code terkadang menghasilkan file markdown dengan tag bahasa yang hilang pada code fence, yang dapat mempengaruhi syntax highlighting dan keterbacaan di GitHub, editor, dan alat dokumentasi.

​

Tag bahasa hilang di blok kode

Jika Anda melihat blok kode seperti ini di markdown yang dihasilkan:

```
function example() {
  return "hello";
}
```

Alih-alih blok yang ditag dengan benar seperti:

```javascript
function example() {
  return "hello";
}
```

Solusi:

1. Minta Claude menambahkan tag bahasa: Cukup minta “Tolong tambahkan tag bahasa yang sesuai ke semua blok kode di file markdown ini.”

2. Gunakan hook post-processing: Siapkan hook formatting otomatis untuk mendeteksi dan menambahkan tag bahasa yang hilang. Lihat contoh hook formatting markdown untuk detail implementasi.

3. Verifikasi manual: Setelah menghasilkan file markdown, tinjau mereka untuk format blok kode yang benar dan minta koreksi jika diperlukan.

​

Spasi dan format yang tidak konsisten

Jika markdown yang dihasilkan memiliki baris kosong berlebihan atau spasi yang tidak konsisten:

Solusi:

1. Minta koreksi format: Minta Claude untuk “Perbaiki masalah spasi dan format di file markdown ini.”

2. Gunakan alat formatting: Siapkan hook untuk menjalankan formatter markdown seperti prettier atau skrip formatting kustom pada file markdown yang dihasilkan.

3. Tentukan preferensi format: Sertakan persyaratan format dalam prompt atau file memory proyek Anda.

​

Praktik terbaik untuk generasi markdown

Untuk meminimalkan masalah format:

• Eksplisit dalam permintaan: Minta “markdown yang diformat dengan benar dengan blok kode yang ditag bahasa”
• Gunakan konvensi proyek: Dokumentasikan gaya markdown yang Anda sukai di CLAUDE.md
• Siapkan hook validasi: Gunakan hook post-processing untuk secara otomatis memverifikasi dan memperbaiki masalah format umum

​

Mendapatkan bantuan lebih lanjut

Jika Anda mengalami masalah yang tidak tercakup di sini:

1. Gunakan perintah /bug dalam Claude Code untuk melaporkan masalah langsung ke Anthropic
2. Periksa repositori GitHub untuk masalah yang diketahui
3. Jalankan /doctor untuk memeriksa kesehatan instalasi Claude Code Anda
4. Tanya Claude langsung tentang kemampuan dan fitur-fiturnya - Claude memiliki akses built-in ke dokumentasinya