​
Masalah instalasi umum

​
Masalah instalasi Windows: error di WSL

Anda mungkin mengalami masalah berikut di WSL:

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

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

Error 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 path Linux yang dimulai dengan /usr/ bukan /mnt/c/. Untuk memperbaiki ini, coba install Node melalui package manager distribusi Linux Anda atau melalui nvm.

Konflik versi nvm: Jika Anda memiliki nvm yang terinstall 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 path Windows (dimulai dengan /mnt/c/), versi Windows sedang digunakan
  • Mengalami fungsi 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 berikut ke file konfigurasi shell Anda (~/.bashrc, ~/.zshrc, dll.):

# Load 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 path Windows masih mengambil prioritas, Anda dapat secara eksplisit menambahkan path Linux Anda ke PATH di konfigurasi shell:

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

Hindari menonaktifkan impor PATH Windows (appendWindowsPath = false) karena ini merusak kemampuan untuk dengan mudah memanggil executable Windows dari WSL. Demikian pula, hindari menguninstall Node.js dari Windows jika Anda menggunakannya untuk pengembangan Windows.

​
Masalah instalasi Linux dan Mac: error permission atau command not found

Saat menginstall Claude Code dengan npm, masalah PATH mungkin mencegah akses ke claude. Anda juga mungkin mengalami error permission jika prefix global npm Anda tidak dapat ditulis oleh user (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.

Installer Claude Code native saat ini dalam beta.

Gunakan perintah berikut untuk menjalankan installer native.

macOS, Linux, WSL:

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

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

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

Windows PowerShell:

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

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

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

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

Pastikan bahwa Anda memiliki direktori instalasi di PATH sistem Anda.

​
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 update di masa depan.

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 path ke executable claude

Verifikasi instalasi:

claude doctor # Periksa kesehatan instalasi

​
Permission dan autentikasi

​
Prompt permission berulang

Jika Anda mendapati diri Anda berulang kali menyetujui perintah yang sama, Anda dapat mengizinkan tool tertentu untuk berjalan tanpa persetujuan menggunakan perintah /permissions. Lihat dokumentasi Permissions.

​
Masalah autentikasi

Jika Anda mengalami masalah autentikasi:

  1. Jalankan /logout untuk sign out 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 mungkin 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 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

​
Masalah pencarian dan penemuan

Jika tool Search, mention @file, agen kustom, dan perintah slash kustom tidak bekerja, install 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 set 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 mungkin menghasilkan kecocokan yang lebih sedikit dari yang diharapkan (tetapi bukan kurangnya fungsi pencarian sepenuhnya) saat menggunakan Claude Code di WSL.

/doctor akan menunjukkan Search sebagai OK dalam kasus ini.

Solusi:

  1. Kirim pencarian yang lebih spesifik: Kurangi jumlah file yang dicari dengan menentukan direktori atau tipe 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 integrasi IDE

​
JetBrains IDE tidak terdeteksi di WSL2

Jika Anda menggunakan Claude Code di WSL2 dengan JetBrains IDE dan mendapat error “No available IDEs detected”, ini kemungkinan karena konfigurasi networking WSL2 atau Windows Firewall memblokir koneksi.

​
Mode networking WSL2

WSL2 menggunakan networking NAT secara default, yang dapat mencegah deteksi IDE. Anda memiliki dua opsi:

Opsi 1: Konfigurasi Windows Firewall (direkomendasikan)

  1. Temukan alamat IP WSL2 Anda:

    wsl hostname -I
# Contoh output: 172.21.123.456

  2. Buka PowerShell sebagai Administrator dan buat aturan firewall:

    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

    (Sesuaikan rentang IP berdasarkan subnet WSL2 Anda dari langkah 1)

  3. Restart IDE dan Claude Code Anda

Opsi 2: Beralih ke mirrored networking

Tambahkan ke .wslconfig di direktori user Windows Anda:

[wsl2]
networkingMode=mirrored

Kemudian restart WSL dengan wsl --shutdown dari PowerShell.

Masalah networking ini hanya mempengaruhi WSL2. WSL1 menggunakan jaringan host secara langsung dan tidak memerlukan konfigurasi ini.

Untuk tips konfigurasi JetBrains tambahan, lihat panduan integrasi IDE kami.

​
Melaporkan masalah integrasi IDE Windows (baik native maupun WSL)

Jika Anda mengalami masalah integrasi IDE di Windows, silakan buat issue dengan informasi berikut: apakah Anda native (git bash), atau WSL1/WSL2, mode networking WSL (NAT atau mirrored), nama/versi IDE, versi ekstensi/plugin Claude Code, dan tipe shell (bash/zsh/dll)

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

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

Untuk memperbaiki masalah ini:

  1. Pergi ke Settings → Tools → Terminal
  2. Pilih salah satu:
    • Uncheck “Move focus to the editor with Escape”, atau
    • Klik “Configure terminal keybindings” dan hapus shortcut “Switch focus to Editor”
  3. Terapkan perubahan

Ini memungkinkan tombol ESC untuk dengan benar menghentikan operasi Claude Code.

​
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 tool 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 diberi tag 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 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 formatting: Minta Claude untuk “Perbaiki masalah spasi dan formatting di file markdown ini.”

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

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

​
Praktik terbaik untuk generasi markdown

Untuk meminimalkan masalah formatting:

  • Eksplisit dalam permintaan: Minta “markdown yang diformat dengan benar dengan blok kode yang diberi tag bahasa”
  • Gunakan konvensi proyek: Dokumentasikan gaya markdown pilihan Anda di CLAUDE.md
  • Siapkan hook validasi: Gunakan hook post-processing untuk secara otomatis memverifikasi dan memperbaiki masalah formatting 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 fiturnya - Claude memiliki akses built-in ke dokumentasinya