Sorun giderme

Yaygın sorunlar ve çözüm adımları.

kodine ile ilgili bir sorunu ayıklamak için önce logları ve diskte saklanan yerel verileri kontrol edin.

Loglar

Log dosyaları şu konuma yazılır:

macOS/Linux: ~/.local/share/kodine/log/
Windows: WIN+R tuşlayıp %USERPROFILE%\.local\share\kodine\log yolunu yapıştırın

Log dosyaları zaman damgasıyla adlandırılır (örneğin 2025-01-09T123456.log) ve en yeni 10 log dosyası tutulur.

Daha ayrıntılı ayıklama bilgisi için --log-level komut satırı seçeneğini kullanabilirsiniz. Örnek: kodine --log-level DEBUG.

Depolama

kodine, oturum verilerini ve diğer uygulama verilerini diskte şu konumda saklar:

macOS/Linux: ~/.local/share/kodine/
Windows: WIN+R tuşlayıp %USERPROFILE%\.local\share\kodine yolunu yapıştırın

Bu dizin şunları içerir:

auth.json - API anahtarları, OAuth token’ları gibi kimlik doğrulama verileri
log/ - Uygulama logları
project/ - Oturum ve mesaj verileri gibi projeye özel veriler
- Proje bir Git deposundaysa ./<project-slug>/storage/ altında saklanır
- Git deposu değilse ./global/storage/ altında saklanır

Masaüstü uygulaması

kodine Desktop arka planda yerel bir kodine sunucusu (kodine-cli sidecar) çalıştırır. Sorunların çoğu bozuk bir eklenti, hasarlı cache veya hatalı sunucu ayarından kaynaklanır.

Hızlı kontroller

Uygulamayı tamamen kapatıp yeniden açın
Uygulama hata ekranı gösteriyorsa Restart’a tıklayıp hata detaylarını kopyalayın
Yalnızca macOS: kodine menüsü -> Reload Webview (arayüz boş/donuksa yardımcı olur)

Eklentileri devre dışı bırakın

Desktop uygulaması açılışta çöküyorsa, takılıyorsa veya garip davranışlar sergiliyorsa önce eklentileri devre dışı bırakın.

Global config’i kontrol edin

Global config dosyanızı açın ve plugin anahtarını arayın.

macOS/Linux: ~/.config/kodine/kodine.jsonc (veya ~/.config/kodine/kodine.json)
macOS/Linux (eski kurulumlar): ~/.local/share/kodine/kodine.jsonc
Windows: WIN+R tuşlayıp %USERPROFILE%\.config\kodine\kodine.jsonc yolunu yapıştırın

Eklenti tanımlıysa anahtarı kaldırarak veya boş bir diziye çekerek geçici olarak devre dışı bırakın:

{
  "$schema": "https://kodine.net/config.json",
  "plugin": [],
}

Eklenti dizinlerini kontrol edin

kodine diskten yerel eklenti de yükleyebilir. Bu dizinleri geçici olarak taşıyın (veya klasörü yeniden adlandırın) ve uygulamayı yeniden başlatın:

Global eklentiler
- macOS/Linux: ~/.config/kodine/plugins/
- Windows: WIN+R tuşlayıp %USERPROFILE%\.config\kodine\plugins yolunu yapıştırın
Proje eklentileri (yalnızca proje bazlı config kullanıyorsanız)
- <your-project>/.kodine/plugins/

Uygulama düzelirse soruna neden olan eklentiyi bulmak için eklentileri tek tek yeniden etkinleştirin.

Cache’i temizleyin

Eklentileri kapatmak işe yaramazsa (veya eklenti kurulumu takılı kaldıysa), kodine’un cache’i yeniden oluşturması için cache’i temizleyin.

kodine Desktop’u tamamen kapatın
Cache dizinini silin:

macOS: Finder -> Cmd+Shift+G -> ~/.cache/kodine
Linux: ~/.cache/kodine dizinini silin (veya rm -rf ~/.cache/kodine çalıştırın)
Windows: WIN+R tuşlayıp %USERPROFILE%\.cache\kodine yolunu yapıştırın

kodine Desktop’u yeniden başlatın

Sunucu bağlantı sorunlarını düzeltin

kodine Desktop ya kendi yerel sunucusunu başlatır (varsayılan) ya da sizin tanımladığınız bir sunucu URL’sine bağlanır.

“Connection Failed” penceresi görüyorsanız (veya uygulama açılış ekranını geçemiyorsa), özel bir sunucu URL’si olup olmadığını kontrol edin.

Desktop varsayılan sunucu URL’sini temizleyin

Ana ekranda sunucu adına (durum noktalı) tıklayarak Server seçicisini açın. Default server bölümünde Clear’a tıklayın.

Config’ten `server.port` / `server.hostname` kaldırın

kodine.json(c) dosyanızda server bölümü varsa geçici olarak kaldırın ve desktop uygulamasını yeniden başlatın.

Ortam değişkenlerini kontrol edin

Ortamda KODINE_PORT ayarlıysa desktop uygulaması yerel sunucu için o portu kullanmaya çalışır.

KODINE_PORT değerini kaldırın (veya boş bir port seçin) ve yeniden başlatın

Linux: Wayland / X11 sorunları

Linux’ta bazı Wayland kurulumları boş pencere veya compositor hatalarına yol açabilir.

Wayland kullanıyorsanız ve uygulama boş/açılmıyorsa OC_ALLOW_WAYLAND=1 ile başlatın
Bu daha kötü olursa kaldırıp X11 oturumunda başlatmayı deneyin

Windows: WebView2 Çalışma Zamanı

Windows’ta kodine Desktop, Microsoft Edge WebView2 Runtime gerektirir. Uygulama boş pencereyle açılıyorsa veya hiç başlamıyorsa WebView2’yi kurup/güncelleyip tekrar deneyin.

Windows: Genel performans sorunları

Windows’ta yavaşlık, dosya erişim sorunları veya terminal problemleri yaşıyorsanız WSL (Windows Subsystem for Linux) kullanmayı deneyin. WSL, kodine özellikleriyle daha sorunsuz çalışan bir Linux ortamı sağlar.

Bildirimler görünmüyor

kodine Desktop sistem bildirimlerini yalnızca şu durumlarda gösterir:

İşletim sistemi ayarlarınızda kodine için bildirimler etkinse
Uygulama penceresi odakta değilse

Desktop depolamasını sıfırlayın (son çare)

Uygulama açılmıyorsa ve ayarları arayüz içinden temizleyemiyorsanız, desktop uygulamasının kayıtlı durumunu sıfırlayın.

kodine Desktop’u kapatın
Şu dosyaları bulun ve silin (kodine Desktop uygulama veri dizininde yer alırlar):

kodine.settings.dat (desktop varsayılan sunucu URL’si)
kodine.global.dat ve kodine.workspace.*.dat (son sunucular/projeler gibi UI durumu)

Dizini hızlıca bulmak için:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (ardından yukarıdaki dosya adlarını aratın)
Linux: ~/.local/share altında bu dosya adlarını aratın
Windows: WIN+R -> %APPDATA% (ardından bu dosya adlarını aratın)

Yardım alın

kodine ile ilgili bir sorun yaşıyorsanız:

GitHub’da issue açın

Hata bildirmek veya özellik talep etmek için en iyi yol GitHub depomuzdur:

github.com/kodine-ai/kodine/issues

Yeni issue açmadan önce sorununuzun daha önce raporlanıp raporlanmadığını kontrol edin.
Discord’a katılın

Gerçek zamanlı yardım ve topluluk sohbeti için Discord sunucumuza katılın:

kodine.net/discord

Yaygın sorunlar

Aşağıda yaygın sorunlar ve çözümleri yer alıyor.

kodine başlamıyor

Hata mesajı için logları kontrol edin
Terminalde çıktı görmek için --print-logs ile çalıştırın
kodine upgrade ile en güncel sürümü kullandığınızdan emin olun

Kimlik doğrulama sorunları

TUI’da /connect komutuyla yeniden kimlik doğrulaması yapın
API anahtarlarınızın geçerli olduğunu kontrol edin
Ağınızın provider API bağlantılarına izin verdiğinden emin olun

Model kullanılamıyor

Provider ile kimlik doğrulaması yaptığınızı kontrol edin
Config’teki model adının doğru olduğunu doğrulayın
Bazı modeller özel erişim veya abonelik gerektirebilir

ProviderModelNotFoundError alıyorsanız büyük olasılıkla bir yerde model referansı yanlıştır. Model referansı şu formatta olmalıdır: <providerId>/<modelId>

Örnekler:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
kodine/kodine-large

Erişiminiz olan modelleri görmek için kodine models çalıştırın.

ProviderInitError

ProviderInitError alıyorsanız büyük olasılıkla config’iniz geçersiz veya bozulmuştur.

Çözüm adımları:

Önce providers rehberini izleyerek provider kurulumunun doğru olduğunu doğrulayın
Sorun sürerse kayıtlı konfigürasyonu temizlemeyi deneyin:
Terminal window
```
rm -rf ~/.local/share/kodine
```
Windows’ta WIN+R tuşlayıp şu konumu silin: %USERPROFILE%\.local\share\kodine
TUI’da /connect komutuyla provider kimlik doğrulamasını tekrar yapın

AI_APICallError ve provider paket sorunları

API çağrısı hataları alıyorsanız bunun nedeni güncel olmayan provider paketleri olabilir. kodine, provider paketlerini (OpenAI, Anthropic, Google vb.) gerektikçe dinamik yükler ve yerelde önbellekler.

Provider paket sorunlarını gidermek için:

Provider paket cache’ini temizleyin:
Terminal window
```
rm -rf ~/.cache/kodine
```
Windows’ta WIN+R tuşlayıp şu konumu silin: %USERPROFILE%\.cache\kodine
En güncel provider paketlerini yeniden kurmak için kodine’u yeniden başlatın

Bu, kodine’un en yeni provider paket sürümlerini indirmesini zorlar ve model parametresi/API değişikliklerinden kaynaklı uyumsuzlukları çoğu zaman çözer.

Linux’ta kopyala/yapıştır çalışmıyor

Linux kullanıcılarının kopyala/yapıştır özelliğinin çalışması için aşağıdaki pano araçlarından en az birini kurması gerekir:

X11 sistemleri için:

apt install -y xclip
# or
apt install -y xsel

Wayland sistemleri için:

apt install -y wl-clipboard

Headless ortamlar için:

apt install -y xvfb
# and run:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

kodine, Wayland kullandığınızı algılarsa wl-clipboard tercihi yapar. Aksi halde sırayla xclip ve xsel araçlarını arar.