Claude Code CLI Kurulum Hataları ve Çözümleri: Kapsamlı Rehber (2026)

Başlamadan Önce: Hazırlık Aşaması (Before You Start)

Claude Code CLI kurmadan önce bilgisayarınızda bazı programların yüklü olması gerekiyor. Endişelenmeyin, hepsini adım adım anlatacağız. Alesta Web ekibi olarak bu rehberi hazırlarken, hiç bilgisayar bilgisi olmayan birinin bile takip edebileceği şekilde yazdık.

Gerekli Programlar (Prerequisites)

• Git - Kod versiyon kontrol sistemi (ücretsiz)
• Node.js 18 veya üzeri - JavaScript çalıştırma ortamı (ücretsiz)
• npm 10 veya üzeri - Node.js paket yöneticisi (Node.js ile birlikte gelir)
• İnternet bağlantısı - Kurulum için gerekli
• Anthropic hesabı - Claude Code kullanmak için gerekli (ücretli abonelik)

Windows Sürümünüzü Kontrol Edin

Bu rehber Windows 10 ve Windows 11 için hazırlanmıştır. Sürümünüzü kontrol etmek için:

# Klavyenizde Windows tuşu + R tuşlarına birlikte basın
# Açılan pencereye yazın: winver
# Enter tuşuna basın
# Açılan pencerede Windows sürümünüzü göreceksiniz

Adım 1: Git Kurulumu (Git Installation - Step by Step)

Git nedir? Git, yazılımcıların kod değişikliklerini takip etmek için kullandığı bir programdır. Claude Code'un düzgün çalışması için Git'in yüklü olması gerekiyor. Alesta Web olarak Git kurulumunu en basit şekilde anlatıyoruz.

Önce Git'in Yüklü Olup Olmadığını Kontrol Edin

# 1. Klavyenizde Windows tuşuna basın
# 2. "cmd" yazın ve Enter'a basın (Komut İstemi açılacak)
# 3. Açılan siyah pencereye şunu yazın:
git --version

# Eğer "git version 2.xx.x" gibi bir şey görürseniz = Git YÜKLÜ,
#    bu adımı atlayabilirsiniz
# Eğer "'git' tanınmıyor" hatası görürseniz = Git YÜKLÜ DEĞİL,
#    aşağıdaki adımları takip edin

Git İndirme ve Kurulum (Eğer Yüklü Değilse)

# 1. İnternet tarayıcınızı açın (Chrome, Firefox, Edge vs.)
# 2. Adres çubuğuna şunu yazın: https://git-scm.com/download/win
# 3. Sayfa açıldığında otomatik olarak indirme başlayacak
# 4. İndirme başlamazsa "Click here to download" linkine tıklayın
# 5. "Git-2.xx.x-64-bit.exe" dosyası indirilecek (yaklaşık 50 MB)

# 1. İndirilen .exe dosyasına çift tıklayın
# 2. "Bu uygulamanın değişiklik yapmasına izin ver?" sorusuna EVET deyin
# 3. Kurulum sihirbazı açılacak, aşağıdaki adımları takip edin:

# Ekran 1: License Agreement
#   → "Next" butonuna tıklayın

# Ekran 2: Select Destination Location
#   → Varsayılan yeri değiştirmeyin, "Next" tıklayın

# Ekran 3: Select Components
#   → Varsayılan seçenekleri değiştirmeyin
#   → "Git Bash Here" seçili olduğundan emin olun
#   → "Next" tıklayın

# Ekran 4: Select Start Menu Folder
#   → "Next" tıklayın

# Ekran 5: Choosing the default editor
#   → "Use Notepad as Git's default editor" seçin (en kolay seçenek)
#   → "Next" tıklayın

# Ekran 6: Adjusting your PATH environment
#   → ÖNEMLİ: "Git from the command line and also from 3rd-party software"
#     seçili olmalı (varsayılan seçenek)
#   → "Next" tıklayın

# Sonraki tüm ekranlarda varsayılan seçenekleri kabul edip "Next" tıklayın
# Son ekranda "Install" butonuna tıklayın
# Kurulum bittiğinde "Finish" tıklayın

# 1. Komut İstemi'ni KAPATIN (eğer açıksa)
# 2. Windows tuşuna basın, "cmd" yazın, Enter'a basın
# 3. Şunu yazın:
git --version

# Şöyle bir çıktı görmelisiniz:
# git version 2.43.0.windows.1

# Bu çıktıyı gördüyseniz Git başarıyla kuruldu!

Adım 2: Node.js Kurulumu (Node.js Installation - Detailed Guide)

Node.js nedir? Node.js, JavaScript kodlarını bilgisayarınızda çalıştırmanızı sağlayan bir programdır. Claude Code, Node.js üzerinde çalışır, bu yüzden mutlaka kurulu olması gerekiyor. Alesta Web olarak iki farklı kurulum yöntemi sunuyoruz.

Önce Node.js'in Yüklü Olup Olmadığını Kontrol Edin

# 1. Komut İstemi'ni açın (Windows tuşu → "cmd" → Enter)
# 2. Şunu yazın:
node --version

# Eğer "v18.x.x" veya "v20.x.x" veya daha yüksek görürseniz = YÜKLÜ
# Eğer "v16.x.x" veya daha düşük görürseniz = GÜNCELLEMENİZ GEREKİYOR
# Eğer "'node' tanınmıyor" görürseniz = YÜKLÜ DEĞİL

# npm'i de kontrol edin:
npm --version

# "10.x.x" veya üzeri olmalı

Yöntem A: Doğrudan Node.js Kurulumu (Başlangıç İçin Önerilen)

# 1. Tarayıcınızda şu adrese gidin: https://nodejs.org
# 2. Sayfada iki yeşil buton göreceksiniz:
#    - Sol taraftaki: "LTS" (Önerilen - Recommended)
#    - Sağ taraftaki: "Current"
# 3. "LTS" butonuna tıklayın (örn: "20.11.0 LTS")
# 4. "node-v20.xx.x-x64.msi" dosyası indirilecek

# 1. İndirilen .msi dosyasına çift tıklayın
# 2. "Bu uygulamanın değişiklik yapmasına izin ver?" → EVET

# Ekran 1: Welcome
#   → "Next" tıklayın

# Ekran 2: License Agreement
#   → "I accept the terms in the License Agreement" kutusunu işaretleyin
#   → "Next" tıklayın

# Ekran 3: Destination Folder
#   → Varsayılanı değiştirmeyin, "Next" tıklayın

# Ekran 4: Custom Setup
#   → Tüm seçenekler varsayılan kalsın
#   → ÖNEMLİ: "Add to PATH" seçili olmalı!
#   → "Next" tıklayın

# Ekran 5: Tools for Native Modules
#   → "Automatically install the necessary tools" kutusunu
#     İŞARETLEMEYİN (gerekli değil)
#   → "Next" tıklayın

# Ekran 6: Ready to install
#   → "Install" tıklayın
#   → Kurulum tamamlandığında "Finish" tıklayın

Yöntem B: NVM ile Kurulum (İleri Seviye - Birden Fazla Sürüm İçin)

Eğer farklı projeler için farklı Node.js sürümleri kullanmanız gerekiyorsa, nvm-windows kullanmanızı öneririz.

# 1. Şu adrese gidin: https://github.com/coreybutler/nvm-windows/releases
# 2. En üstteki "Assets" bölümünü açın
# 3. "nvm-setup.exe" dosyasını indirin
# 4. İndirilen dosyayı çalıştırın ve kurulum sihirbazını takip edin

# ÖNEMLİ: Symlink klasörü sorulduğunda varsayılan yolu
# "C:\Program Files\nodejs" yerine "C:\nodejs" olarak değiştirin
# (boşluk içermeyen bir yol seçin)

# Kurulum bittikten sonra:
# 1. Komut İstemi'ni KAPATIN
# 2. YENİ bir Komut İstemi açın (YÖNETİCİ OLARAK)
#    Windows tuşu → "cmd" yaz → Sağ tık → "Yönetici olarak çalıştır"

# 3. Şu komutları sırayla çalıştırın:
nvm install lts
nvm use lts

# Doğrulama:
node --version
npm --version

# Komut İstemi'ni KAPATIN ve YENİDEN açın
# (Bu çok önemli, PATH güncellemesi için gerekli)

# Şu komutları yazın:
node --version
# Beklenen çıktı: v20.11.0 (veya benzeri)

npm --version
# Beklenen çıktı: 10.2.4 (veya benzeri)

# Her iki komut da sürüm numarası gösteriyorsa başarılı!

Adım 3: PowerShell Ayarları (PowerShell Configuration)

Claude Code kurulumu için PowerShell kullanacağız. PowerShell, Windows'un gelişmiş komut satırı aracıdır. Alesta Web olarak bu adımı atlamanızı önermiyoruz çünkü Claude Code kurulum scripti PowerShell gerektirir.

PowerShell'i Açma

# Yöntem 1 (En Kolay):
# 1. Windows tuşuna basın
# 2. "powershell" yazın
# 3. "Windows PowerShell" üzerine SAĞ TIKLAYIN
# 4. "Yönetici olarak çalıştır" seçin
# 5. "Evet" deyin

# Yöntem 2:
# 1. Windows tuşu + X tuşlarına birlikte basın
# 2. "Windows PowerShell (Yönetici)" seçin

# Yöntem 3:
# 1. Başlat menüsüne sağ tıklayın
# 2. "Windows Terminal (Yönetici)" seçin

PowerShell Execution Policy Ayarı

Windows güvenlik nedeniyle bazı scriptlerin çalışmasını engelleyebilir. Bu ayarı değiştirmemiz gerekiyor.

# PowerShell'de (Yönetici olarak) şunu yazın:
Get-ExecutionPolicy

# Eğer "Restricted" yazıyorsa, aşağıdaki komutu çalıştırın:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# "Execution Policy Change" uyarısı çıkarsa "Y" yazıp Enter'a basın

# Tekrar kontrol edin:
Get-ExecutionPolicy
# Şimdi "RemoteSigned" yazmalı

Adım 4: Claude Code CLI Kurulumu (The Main Installation)

Artık tüm ön hazırlıklar tamam! Şimdi Claude Code CLI'ı kuracağız. Alesta Web olarak iki kurulum yöntemi sunuyoruz. Native kurulum yöntemini öneriyoruz çünkü daha az sorunla karşılaşıyorsunuz.

Yöntem 1: Native Kurulum (Önerilen / Recommended)

# 1. PowerShell'i YÖNETİCİ OLARAK açın
# 2. Şu komutu kopyalayıp yapıştırın:

irm https://claude.ai/install.ps1 | iex

# 3. Enter'a basın ve bekleyin
# 4. Kurulum otomatik olarak tamamlanacak
# 5. "Installation complete!" mesajını görmelisiniz

Yöntem 2: npm ile Kurulum (Alternatif)

# PowerShell veya Komut İstemi'nde:
npm install -g @anthropic-ai/claude-code

# Kurulum tamamlandığında şöyle bir çıktı göreceksiniz:
# added 1 package in Xs

Kurulum Sonrası PATH Ayarı (Çok Önemli!)

Native kurulum PATH'i otomatik ayarlamayabilir. Aşağıdaki adımları takip edin:

# Yöntem 1: PowerShell ile (Geçici - Terminal kapatılana kadar)
$env:PATH += ";$env:USERPROFILE\.local\bin"

# Yöntem 2: Kalıcı olarak eklemek için:
# 1. Windows tuşu + R basın
# 2. "sysdm.cpl" yazın ve Enter'a basın
# 3. "Gelişmiş" (Advanced) sekmesine tıklayın
# 4. "Ortam Değişkenleri" (Environment Variables) butonuna tıklayın
# 5. "Kullanıcı değişkenleri" bölümünde "Path" seçin
# 6. "Düzenle" (Edit) tıklayın
# 7. "Yeni" (New) tıklayın
# 8. Şunu yapıştırın: %USERPROFILE%\.local\bin
# 9. "Tamam" tıklayarak tüm pencereleri kapatın

# Yöntem 3: PowerShell ile Kalıcı Ekleme
[Environment]::SetEnvironmentVariable(
    "PATH",
    "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin",
    "User"
)

# ÖNEMLİ: PATH değişikliğinden sonra PowerShell'i KAPATIN ve YENİDEN AÇIN!

Adım 5: Kurulum Doğrulama (Verification)

Kurulumun başarılı olup olmadığını kontrol edelim. Alesta Web olarak bu adımı asla atlamayın diyoruz!

# 1. PowerShell veya Komut İstemi'ni KAPATIN
# 2. YENİ bir pencere açın
# 3. Şunu yazın:

claude --version

# Beklenen çıktı (örnek):
# claude-code version 2.1.12

# Eğer sürüm numarası görüyorsanız = KURULUM BAŞARILI! ?
# Eğer "'claude' tanınmıyor" hatası görüyorsanız = PATH sorunu var,
#    yukarıdaki PATH ayarlarını kontrol edin

Claude Doctor ile Otomatik Tanı

Claude Code'un harika bir özelliği var: claude doctor komutu! Bu komut sisteminizi kontrol eder ve sorunları tespit eder.

# Temel tanı:
claude doctor

# Bu komut şunları kontrol eder:
# ✅ Node.js versiyonu ve uyumluluğu
# ✅ PATH yapılandırması
# ✅ API anahtarı durumu
# ✅ Ağ bağlantısı
# ✅ Yapılandırma dosyaları

# Detaylı çıktı için:
claude doctor --verbose

Adım 6: İlk Kullanım ve API Anahtarı (First Use & API Key)

Claude Code kuruldu ama henüz kullanıma hazır değil. Anthropic hesabınızla giriş yapmanız gerekiyor.

Anthropic Hesabı Oluşturma

# 1. Tarayıcınızda şu adrese gidin: https://console.anthropic.com
# 2. "Sign Up" butonuna tıklayın
# 3. E-posta adresinizi girin veya Google ile kaydolun
# 4. E-postanıza gelen doğrulama linkine tıklayın
# 5. Hesabınızı oluşturun

# ÖNEMLİ: Claude Code kullanmak için ücretli abonelik gereklidir!
# Fiyatlandırma için: https://www.anthropic.com/pricing

Claude Code'a Giriş Yapma

# 1. Terminal açın (PowerShell veya CMD)
# 2. Şunu yazın:

claude

# 3. İlk çalıştırmada tarayıcınız otomatik açılacak
# 4. Anthropic hesabınızla giriş yapın
# 5. "Authorize" butonuna tıklayın
# 6. Terminal'e dönün - artık Claude Code kullanıma hazır!

# Alternatif: API Key ile giriş
# Eğer tarayıcı açılmazsa veya sorun yaşarsanız:
claude auth login

# veya API anahtarınızı doğrudan girin:
claude auth login --api-key YOUR_API_KEY

İlk Komutunuzu Çalıştırın

# Basit bir test:
claude "Merhaba, nasılsın?"

# Proje dizininde çalışmak için:
cd C:\Users\KULLANICI_ADINIZ\projelerim
claude

# İnteraktif mod başlayacak, artık Claude ile sohbet edebilirsiniz!

En Sık Karşılaşılan Hatalar ve Çözümleri (Most Common Errors & Fixes)

Aşağıda Claude Code CLI kurulumunda en sık karşılaşılan hataları ve çözümlerini derledik. Alesta Web ekibi olarak bu hataların çoğunu kendimiz de yaşadık!

? Hata 1: "command not found: claude" veya "'claude' tanınmıyor"

Sebep: Claude Code kuruldu ama PATH'e eklenmedi.

# Windows için:
# 1. Win + R basın, "sysdm.cpl" yazın, Enter
# 2. Gelişmiş → Ortam Değişkenleri
# 3. Kullanıcı değişkenlerinde "Path" seçin → Düzenle → Yeni
# 4. Ekleyin: %USERPROFILE%\.local\bin
# 5. Tamam'a tıklayıp tüm pencereleri kapatın
# 6. Terminal'i KAPATIN ve YENİDEN AÇIN

# npm kurulumu yaptıysanız, npm global klasörünü ekleyin:
# %APPDATA%\npm

? Hata 2: "Node.js version 18 or higher required"

Sebep: Eski Node.js sürümü yüklü.

# Mevcut sürümü kontrol edin:
node --version

# Node.js'i güncelleyin:
# 1. https://nodejs.org adresine gidin
# 2. LTS sürümünü indirin ve kurun
# 3. Kurulum sırasında "eski sürümü kaldır" seçeneğini işaretleyin

# veya NVM kullanıyorsanız:
nvm install lts
nvm use lts

? Hata 3: "EACCES: permission denied" (İzin Hatası)

Sebep: Yeterli yetki yok.

# 1. ASLA "sudo" veya "Run as Administrator" ile npm install yapmayın!
# 2. Bunun yerine npm global dizinini değiştirin:

npm config set prefix "$env:USERPROFILE\.npm-global"

# 3. PATH'e ekleyin: %USERPROFILE%\.npm-global
# 4. Tekrar deneyin:
npm install -g @anthropic-ai/claude-code

? Hata 4: "Stale lock file" (Eski Kilit Dosyası)

Sebep: Önceki kurulum denemesinden kalan kilit dosyası.

# Windows PowerShell'de:
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\state\claude\locks" -ErrorAction SilentlyContinue

# Sonra tekrar kurulum yapın:
irm https://claude.ai/install.ps1 | iex

? Hata 5: "PowerShell script execution disabled"

Sebep: Windows script çalıştırmayı engelliyor.

# PowerShell'i YÖNETİCİ olarak açın ve şunu çalıştırın:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# "Y" yazıp Enter'a basın
# Sonra kurulumu tekrar deneyin

? Hata 6: "Windows installer reports success but .local\bin is empty"

Sebep: Bilinen bir Windows bug'ı - indirme sessizce başarısız oluyor.

# PowerShell'de şu komutları sırayla çalıştırın:

# 1. Klasörü oluşturun:
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.local\bin"

# 2. Sürüm bilgisini alın:
$version = Invoke-RestMethod -Uri "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/stable"

# 3. Binary'yi indirin:
$url = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/$version/win32-x64/claude.exe"
Invoke-WebRequest -Uri $url -OutFile "$env:USERPROFILE\.local\bin\claude.exe"

# 4. PATH'e ekleyin (yukarıdaki adımlara bakın)

# 5. Doğrulayın:
claude --version

? Hata 7: "exec: node: not found" (WSL'de)

Sebep: WSL, Windows Node.js'ini kullanmaya çalışıyor.

# WSL terminalinde:

# 1. NVM kurun:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 2. Terminal'i kapatıp açın

# 3. Node.js kurun:
nvm install --lts
nvm use --lts

# 4. Kontrol edin (yol /home/... ile başlamalı, /mnt/c/... DEĞİL):
which node

# 5. Claude Code'u kurun:
curl -fsSL https://claude.ai/install.sh | bash

? Hata 8: "API rate limit exceeded" veya "Authentication failed"

Sebep: API anahtarı sorunu veya abonelik sorunu.

# 1. Mevcut oturumu temizleyin:
claude auth logout

# 2. Tekrar giriş yapın:
claude auth login

# 3. Anthropic hesabınızda:
#    - Fatura bilgilerinizi kontrol edin
#    - Aboneliğinizin aktif olduğundan emin olun
#    - API kullanım limitinizi kontrol edin

? Hata 9: "SSL certificate problem"

Sebep: Ağ/proxy sorunu.

# Kurumsal ağda veya VPN kullanıyorsanız:

# 1. Proxy ayarlarını kontrol edin:
npm config list

# 2. Gerekirse proxy ayarlayın:
npm config set proxy http://proxy.sirketiniz.com:8080
npm config set https-proxy http://proxy.sirketiniz.com:8080

# 3. veya SSL doğrulamayı geçici olarak devre dışı bırakın (önerilmez):
npm config set strict-ssl false

? Hata 10: "Segmentation fault" veya "Unexpected crash"

Sebep: Karışık kurulum (npm + native).

# Her şeyi kaldırın ve native kurulum yapın:

# 1. npm paketini kaldırın:
npm uninstall -g @anthropic-ai/claude-code

# 2. Tüm Claude dosyalarını silin:
Remove-Item -Recurse -Force "$env:USERPROFILE\.local" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude" -ErrorAction SilentlyContinue

# 3. npm cache temizleyin:
npm cache clean --force

# 4. PowerShell'i kapatıp YÖNETİCİ olarak açın

# 5. Native kurulum yapın:
irm https://claude.ai/install.ps1 | iex

Temiz Kurulum Rehberi (Complete Clean Installation)

Tüm çözümler işe yaramadıysa, temiz bir kurulum yapmanız gerekebilir. Alesta Web ekibi olarak bu yöntemi son çare olarak öneriyoruz ama genellikle işe yarıyor.

# PowerShell'i YÖNETİCİ olarak açın

# ADIM 1: Tüm Claude dosyalarını silin
Remove-Item -Recurse -Force "$env:USERPROFILE\.local" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:APPDATA\claude-code" -ErrorAction SilentlyContinue

# ADIM 2: npm paketini kaldırın (eğer varsa)
npm uninstall -g @anthropic-ai/claude-code 2>$null

# ADIM 3: npm cache temizleyin
npm cache clean --force

# ADIM 4: PowerShell'i KAPATIN

# ADIM 5: Bilgisayarınızı YENİDEN BAŞLATIN (önerilir)

# ADIM 6: PowerShell'i YÖNETİCİ olarak açın

# ADIM 7: Native kurulum yapın
irm https://claude.ai/install.ps1 | iex

# ADIM 8: PATH'i ekleyin (otomatik eklenmezse)
[Environment]::SetEnvironmentVariable(
    "PATH",
    "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin",
    "User"
)

# ADIM 9: PowerShell'i KAPATIN ve YENİDEN AÇIN

# ADIM 10: Doğrulayın
claude --version
claude doctor

Kaynaklar ve Referanslar (Sources & References)

Bu rehberde kullanılan bilgiler aşağıdaki güvenilir kaynaklardan derlenmiştir:

• Claude Code Official Setup Docs - Resmi kurulum rehberi
• Claude Code Troubleshooting - Resmi sorun giderme
• Claude Code GitHub Issues - Topluluk hata raporları
• npm - @anthropic-ai/claude-code - npm paketi
• Git for Windows - Git indirme sayfası
• Node.js Official - Node.js indirme
• nvm-windows GitHub - Windows için NVM
• InterWorks - Windows 11 Guide - Windows 11 rehberi
• Vibe Coding Installation Guide - Detaylı kurulum
• ClaudeLog Troubleshooting - Sorun giderme

Alesta Web olarak tüm bu bilgileri test ettik ve doğruladık.