Sorun giderme

Yaygin sorunlar ve cozum adimlari.

matrix ile ilgili bir sorunu ayiklamak icin once loglari ve diskte tuttugu yerel verileri kontrol edin.

Loglar

Log dosyalari su konuma yazilir:

macOS/Linux: ~/.local/share/matrix/log/
Windows: WIN+R tuslayip %USERPROFILE%\.local\share\matrix\log yapistirin

Log dosyalari zaman damgasiyla adlandirilir (ornegin 2025-01-09T123456.log) ve en yeni 10 log dosyasi tutulur.

Daha ayrintili ayiklama bilgisi icin --log-level komut satiri secenegini kullanabilirsiniz. Ornek: matrix --log-level DEBUG.

Depolama

matrix, oturum verilerini ve diger uygulama verilerini diskte su konumda saklar:

macOS/Linux: ~/.local/share/matrix/
Windows: WIN+R tuslayip %USERPROFILE%\.local\share\matrix yapistirin

Bu dizin sunlari icerir:

auth.json - API anahtarlari, OAuth tokenlari gibi kimlik dogrulama verileri
log/ - Uygulama loglari
project/ - Oturum ve mesaj verileri gibi projeye ozel veriler
- Proje bir Git deposundaysa ./<project-slug>/storage/ altinda saklanir
- Git deposu degilse ./global/storage/ altinda saklanir

Masaüstü uygulaması

matrix Desktop arka planda yerel bir matrix sunucusu (matrix-cli sidecar) calistirir. Sorunlarin cogu bozuk bir plugin, hasarli cache veya hatali sunucu ayarindan kaynaklanir.

Hızlı kontroller

Uygulamayi tamamen kapatip yeniden acin
Uygulama hata ekrani gosteriyorsa Restart’a tiklayip hata detaylarini kopyalayin
Yalnizca macOS: matrix menusu -> Reload Webview (arayuz bos/donukse yardimci olur)

Eklentileri devre dışı bırakın

Desktop uygulamasi acilista cokuyorsa, takiliyorsa veya garip davranislar gosteriyorsa once pluginleri devre disi birakin.

Global config’i kontrol edin

Global config dosyanizi acin ve plugin anahtarini arayin.

macOS/Linux: ~/.config/matrix/matrix.jsonc (veya ~/.config/matrix/matrix.json)
macOS/Linux (eski kurulumlar): ~/.local/share/matrix/matrix.jsonc
Windows: WIN+R tuslayip %USERPROFILE%\.config\matrix\matrix.jsonc yapistirin

Plugin tanimliysa anahtari kaldirarak veya bos bir diziye cekerek gecici olarak devre disi birakin:

{
  "$schema": "https://y-square-t3.github.io/matrix/config.json",
  "plugin": [],
}

Eklenti dizinlerini kontrol edin

matrix diskten yerel plugin de yukleyebilir. Bu dizinleri gecici olarak tasiyin (veya klasoru yeniden adlandirin) ve uygulamayi yeniden baslatin:

Global plugins
- macOS/Linux: ~/.config/matrix/plugins/
- Windows: WIN+R tuslayip %USERPROFILE%\.config\matrix\plugins yapistirin
Project plugins (sadece proje bazli config kullaniyorsaniz)
- <your-project>/.matrix/plugins/

Uygulama duzelirse soruna neden olan plugini bulmak icin pluginleri tek tek yeniden etkinlestirin.

Cache’i temizleyin

Pluginleri kapatmak ise yaramazsa (veya plugin kurulumu takili kaldiysa), matrix’un cache’i yeniden olusturmasi icin cache’i temizleyin.

matrix Desktop’u tamamen kapatin
Cache dizinini silin:

macOS: Finder -> Cmd+Shift+G -> ~/.cache/matrix
Linux: ~/.cache/matrix dizinini silin (veya rm -rf ~/.cache/matrix calistirin)
Windows: WIN+R tuslayip %USERPROFILE%\.cache\matrix yapistirin

matrix Desktop’u yeniden baslatin

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

matrix Desktop ya kendi yerel sunucusunu baslatir (varsayilan) ya da sizin tanimladiginiz bir sunucu URL’sine baglanir.

“Connection Failed” penceresi goruyorsaniz (veya uygulama acilis ekranini gecemiyorsa), ozel bir sunucu URL’si olup olmadigini kontrol edin.

Desktop varsayilan sunucu URL’sini temizleyin

Ana ekranda sunucu adina (durum noktali) tiklayarak Server secicisini acin. Default server bolumunde Clear’a tiklayin.

Config’ten `server.port` / `server.hostname` kaldirin

matrix.json(c) dosyanizda server bolumu varsa gecici olarak kaldirin ve desktop uygulamasini yeniden baslatin.

Ortam degiskenlerini kontrol edin

Ortamda MATRIX_PORT ayarliysa desktop uygulamasi yerel sunucu icin o portu kullanmaya calisir.

MATRIX_PORT degerini kaldirin (veya bos bir port secin) ve yeniden baslatin

Linux: Wayland / X11 sorunları

Linux’ta bazi Wayland kurulumlari bos pencere veya compositor hatalarina yol acabilir.

Wayland kullaniyorsaniz ve uygulama bos/acilmiyorsa OC_ALLOW_WAYLAND=1 ile baslatin
Bu daha kotu olursa kaldirip X11 oturumunda baslatmayi deneyin

Windows: WebView2 Çalışma Zamanı

Windows’ta matrix Desktop, Microsoft Edge WebView2 Runtime gerektirir. Uygulama bos pencereyle aciliyorsa veya hic baslamiyorsa WebView2’yi kurup/guncelleyip tekrar deneyin.

Windows: Genel performans sorunları

Windows’ta yavaslik, dosya erisim sorunlari veya terminal problemleri yasiyorsaniz WSL (Windows Subsystem for Linux) kullanmayi deneyin. WSL, matrix ozellikleriyle daha sorunsuz calisan bir Linux ortami saglar.

Bildirimler görünmüyor

matrix Desktop sistem bildirimlerini yalnizca su durumlarda gosterir:

Isletim sistemi ayarlarinizda matrix icin bildirimler etkinse
Uygulama penceresi odakta degilse

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

Uygulama acilmiyorsa ve ayarlari arayuz icinden temizleyemiyorsaniz, desktop uygulamasinin kayitli durumunu sifirlayin.

matrix Desktop’u kapatin
Su dosyalari bulun ve silin (matrix Desktop uygulama veri dizininde yer alirlar):

matrix.settings.dat (desktop varsayilan sunucu URL’si)
matrix.global.dat ve matrix.workspace.*.dat (son sunucular/projeler gibi UI durumu)

Dizini hizlica bulmak icin:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (ardindan yukaridaki dosya adlarini aratin)
Linux: ~/.local/share altinda bu dosya adlarini aratin
Windows: WIN+R -> %APPDATA% (ardindan bu dosya adlarini aratin)

Yardım alın

matrix ile ilgili bir sorun yasiyorsaniz:

GitHub’da issue acin

Hata bildirmek veya ozellik talep etmek icin en iyi yol GitHub depomuzdur:

github.com/Y-Square-T3/matrix/issues

Yeni issue acmadan once sorununuzun daha once raporlanip raporlanmadigini kontrol edin.
Discord’a katilin

Gercek zamanli yardim ve topluluk sohbeti icin Discord sunucumuza katilin:

y-square-t3.github.io/matrix/discord

Yaygın sorunlar

Asagida yaygin sorunlar ve cozumleri yer aliyor.

matrix başlamıyor

Hata mesaji icin loglari kontrol edin
Terminalde cikti gormek icin --print-logs ile calistirin
matrix upgrade ile en guncel surumu kullandiginizdan emin olun

Kimlik doğrulama sorunları

TUI’da /connect komutuyla yeniden kimlik dogrulamasi yapin
API anahtarlarinizin gecerli oldugunu kontrol edin
Aginizin provider API baglantilarina izin verdiginden emin olun

Model kullanılamıyor

Provider ile kimlik dogrulamasi yaptiginizi kontrol edin
Config’teki model adinin dogru oldugunu dogrulayin
Bazi modeller ozel erisim veya abonelik gerektirebilir

ProviderModelNotFoundError aliyorsaniz buyuk olasilikla bir yerde model referansi yanlistir. Model referansi su formatta olmalidir: <providerId>/<modelId>

Ornekler:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
matrix/kimi-k2

Erisiminiz olan modelleri gormek icin matrix models calistirin.

ProviderInitError

ProviderInitError aliyorsaniz buyuk olasilikla config’iniz gecersiz veya bozulmustur.

Cozum adimlari:

Once providers rehberini izleyerek provider kurulumunun dogru oldugunu dogrulayin
Sorun surerse kayitli konfigurasyonu temizlemeyi deneyin:
Terminal window
```
rm -rf ~/.local/share/matrix
```
Windows’ta WIN+R tuslayip su konumu silin: %USERPROFILE%\.local\share\matrix
TUI’da /connect komutuyla provider kimlik dogrulamasini tekrar yapin

AI_APICallError ve provider paket sorunlari

API cagrisi hatalari aliyorsaniz bunun nedeni guncel olmayan provider paketleri olabilir. matrix, provider paketlerini (OpenAI, Anthropic, Google vb.) gerektikce dinamik yukler ve yerelde onbellekler.

Provider paket sorunlarini gidermek icin:

Provider paket cache’ini temizleyin:
Terminal window
```
rm -rf ~/.cache/matrix
```
Windows’ta WIN+R tuslayip su konumu silin: %USERPROFILE%\.cache\matrix
En guncel provider paketlerini yeniden kurmak icin matrix’u yeniden baslatin

Bu, matrix’un en yeni provider paket surumlerini indirmesini zorlar ve model parametresi/API degisikliklerinden kaynakli uyumsuzluklari cogu zaman cozer.

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

Linux kullanicilarinin kopyala/yapistir ozelliginin calismasi icin asagidaki pano araclarindan en az birini kurmasi gerekir:

X11 sistemleri icin:

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

Wayland sistemleri icin:

apt install -y wl-clipboard

Headless ortamlar icin:

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

matrix, Wayland kullandiginizi algilarsa wl-clipboard tercihi yapar. Aksi halde sirayla xclip ve xsel araclarini arar.