# Sorun Giderme > Başlangıç, oturum açma, kaynak, indeksleme ve arama sorunları için tam hata mesajları, nedenleri ve çözümleriyle eşleştirilmiş. - Güncelleme: 2026-09-25 - Kaynak: https://contextator.com/tr/docs/troubleshooting/ - Dil: tr-TR - Yazar: Muhammet Şafak --- Buradan başlayın: panonun üst çubuğu size veritabanının ayakta olup olmadığını ve modelin hazır olup olmadığını söyler, ve başarısız bir proje hatasını ayrıntı görünümünde olduğu gibi gösterir. Log'lar `docker compose logs -f`'tedir. --- ## Başlangıç ### Konteyner sürekli yeniden başlıyor Çıkışın üstündeki log satırı hangi sürecin öldüğünü söyler. - *"PostgreSQL exited during startup"* — üstündeki PostgreSQL çıktısı nedenini açıklar. Genellikle başka bir PostgreSQL ana sürümü tarafından oluşturulmuş bir veri dizini, ya da izinleri düzeltilemeyen bir bind-mount edilmiş `CONTEXTATOR_PGDATA_PATH`. Docker Desktop'ta, veritabanını bir adlandırılmış volume'e geri taşımak güvenilir çözümdür. - Geçersiz bir yapılandırma — sunucu her sorunu yazdırır ve çıkar. `.env`'i düzeltin ve yeniden başlatın. ### `The database was created with EMBEDDING_DIMENSIONS=… but the current config says …` Gömme boyutlarını değiştirdiniz. Ya eski değeri geri yükleyin, ya da `RESET_VECTORS=1` ile bir kez başlatın (her parçayı düşürür) ve her şeyi yeniden indeksleyin. Bkz. [Gömme Modelleri](/tr/docs/embedding-models/). ### Pano uzun süre "Model loading" diyor İlk başlangıç ~470 MB indirir. `docker compose logs -f`'i `downloading model file` ve ardından `embedding model ready` için izleyin. Daha az indirmek için, ilk başlangıçtan önce `EMBEDDING_DTYPE=q8` (~120 MB) ayarlayın. Havadan izole bir host'ta, modeller volume'ünü önceden doldurun ve `EMBEDDING_OFFLINE=1` ayarlayın. Model hazır olana kadar, panonun geri kalanı çalışırken indeksleme ve arama başarısız olur. ### `Could not load the sharp module` Kilit dosyası başka bir platformda üretildi. `package-lock.json`'ı Linux'ta yeniden üretin, ya da imajı build etmeden önce `npm install --os=linux --cpu=x64 sharp` çalıştırın. --- ## Oturum açmak ### Pano beni `/setup`'a gönderiyor Bu örneğin henüz hiç hesabı yok. Kurulum kodu logdadır — `docker compose logs -f` — ilk hesap var olana kadar her başlangıçta bir kutunun içinde yazdırılır. Bkz. [Hesaplar ve İzinler](/tr/docs/accounts-and-permissions/). ### `That setup code is not the one in the server log` Daha eski bir kutuyu okuyorsunuz. Üretilen bir kod her yeniden başlatmada değiştirilir, bu yüzden en yenisini kullanın, ya da onu yerinde sabitlemek için `.env`'de `SETUP_CODE` ayarlayın ve yeniden başlatın. Büyük/küçük harf, tire ve boşluk önemli değildir. ### Oturum açmak başarılı oluyor, sonra doğrudan `/login`'e geri sekiyor Tarayıcı oturum çerezini düşürüyor. Düz-HTTP bir adreste — TLS'siz bir LAN IP'si ya da hostname — `AUTH_COOKIE_SECURE=0` ayarlayın ve yeniden başlatın. TLS'yi sonlandıran bir proxy'nin arkasında, onu `1`'e ayarlayın. ### `Wrong username or password`, ve doğru olduğundan eminim Mesaj, bilinmeyen bir kullanıcı adı ve yanlış bir parola için kasıtlı olarak aynıdır, bu yüzden önce kullanıcı adının var olup olmadığını kontrol edin. Varsa, hesap o zamandan beri sıfırlanmış geçici bir parolayla yeni olabilir — onu oluşturana sorun. `Too many failed attempts; this account is locked for a while`, kilitlenmenin çalıştığı anlamına gelir: `AUTH_LOGIN_WINDOW_MIN` dakikada başlar ve bir saate kadar iki katına çıkar. ### Oturum açma *too many attempts* diyor Kendi hesabında bir kilitlenme değil, hız sınırlamadır: IP adresi başına, `AUTH_LOGIN_WINDOW_MIN` dakika içinde `AUTH_LOGIN_MAX_ATTEMPTS` başarısızlık bir `Retry-After` ile bir `429` alır. Bekleyin, ya da iki değişkenden birini yükseltin. ### Kimse hiç oturum açamıyor Bkz. [Parolamı unuttum](/tr/docs/faq/). Kısa versiyon: başka bir admin onu sıfırlar, ya da `ADMIN_TOKEN` bunu API üzerinden yapar, ya da bir kaynak kurulumunda `npm run reset-password -- `. ### Son root hesabını silemiyorum Tasarım gereği — sunucu `409` yanıtlar ve pano düğmeyi devre dışı bırakır, böylece bir örnek kendi kullanıcı yönetiminin dışında asla kilitli kalamaz. Önce başka birini `root`'a yükseltin. Bkz. [Hesaplar ve İzinler](/tr/docs/accounts-and-permissions/#roller). ### Var olduğunu bildiğim bir proje `404` yanıtlıyor Hesabınız onun bir üyesi değil. Bu kasıtlıdır — erişim yok ile böyle bir proje yok aynı şekilde yanıt verir — bu yüzden bir `root` ya da `admin`'den sizi proje sayfasındaki **Members** altına eklemesini isteyin. --- ## Kaynaklar ### `Directory is outside the allowed document roots` Yol `ALLOWED_DOC_ROOTS` içinde çözümlenmelidir — Docker içinde bu `/docs/...` anlamına gelir. Ya böyle bir yol kullanın, ya da klasörü bağlayın ve `ALLOWED_DOC_ROOTS`'a ekleyin, ardından yeniden başlatın. Bkz. [Yerel Klasör Kaynağı](/tr/docs/local-directory-source/). ### Bir git kaynağı bir kimlik doğrulama hatası gösteriyor **Test connection**, uzak sunucunun kendi yanıtını bildirir. Token'ın depoya okuma erişimi olduğunu ve süresinin dolmadığını kontrol edin. Bir Bitbucket deposu ya da workspace erişim token'ı için **Username**'i boş bırakın (varsayılan `x-token-auth` yalnızca onlar içindir); bir **Bitbucket Cloud API token**'ı o alanda Bitbucket kullanıcı adınızı, ya da `x-bitbucket-api-token-auth`'u gerektirir; bir **GitLab deploy token**'ı kendi üretilen kullanıcı adını gerektirir, örn. `gitlab+deploy-token-42` — varsayılan `oauth2` bir deploy token'ı için reddedilir. Sağlayıcıya göre tam tablo için bkz. [Git Deposu Kaynağı](/tr/docs/git-repository-source/#özel-depolar). ### `Subdirectory "…" does not exist in the repository` Yol depo köküne görecelidir ve yapılandırdığınız branch'e karşı kontrol edilir. İkisini de doğrulayın. ### `Branch "…" was not found on the remote` Yanlış branch adı — genellikle `main` yerine `master`. ### Özel bir git, Notion ya da Confluence kaynağı eklemek `SECRET_KEY`'de başarısız oluyor `SECRET_KEY`'i (32+ karakter, örn. `openssl rand -hex 32`) ayarlayın ve yeniden başlatın. Yalnızca bir kaynağın bir token saklaması gerektiğinde gereklidir. ### Daha önce çalışan bir kaynak artık token'ın şifresinin çözülemediğini söylüyor `SECRET_KEY` değişti. Eski anahtarı hâlâ elinizde tutuyorsanız, hiçbir şeyi yeniden girmenize gerek yok: `SECRET_KEY_PREVIOUS`'u ona, yeni `SECRET_KEY`'in yanına ayarlayın, yeniden başlatın, saklanan her token'ı yeni anahtar altında yeniden şifrelemek için `npm run rotate-secret`'ı (bir Docker kurulumu için `docker exec contextator npm run rotate-secret`) çalıştırın, ardından altında hiçbir şey kalmadığını bildirince `SECRET_KEY_PREVIOUS`'u kaldırın ve yeniden başlatın. Eski anahtar tamamen kayıpsa, bunun yerine o kaynak için token'ı yeniden girin — kurtarılamaz. Bkz. [Güvenlik](/tr/docs/security/#şeyleri-değiştirmek). ### Notion hiçbir şey içeri almıyor Henüz integration ile hiçbir şey paylaşılmadı. Notion'da, sayfaları ya da veritabanlarını onunla paylaşın (**… → Connections**). Bu şekilde paylaşılan bir sayfa çocuklarını da içerir. Bkz. [Notion](/tr/docs/notion/). ### Notion hiçbir root okunamadığını söylüyor Token yanlış ya da root id'leri integration ile paylaşılmamış. Contextator, boş bir çalışma alanı bildirmek yerine kasıtlı olarak burada başarısız olur — ki bu daha önce içeri alınan her sayfayı silerdi. ### Bir yükleme bazı dosyaları reddetti Yanıt nelerin atlandığını ve nedenini listeler: kaynağın indekslemediği bir uzantı, bir nokta-dizini, platformlar arasında taşınabilir olmayan bir ad, hedefi aşan bir girdi, ya da bir boyut sınırı. Kaynağın dosya türlerini, ya da [Yapılandırma](/tr/docs/configuration/)'daki sınırları ayarlayın. --- ## İndeksleme ### Bir proje `indexing`'te takılı kalıyor Canlı job durumu bellekte yaşar, bu yüzden çalışma ortasında bir yeniden başlatma durumu geride bırakabilir. **Re-index**'e basın — çalışma artımlıdır ve ucuza devam eder, ve durum yeniden yazılır. ### Proje `error` ama çoğu doküman orada Bir kaynak başarısız oldu ve geri kalanı indekslendi. Mesaj `2/3 sources synced; : ` okur, ve başarısız olan kaynağın satırı tam hatayı taşır. Onu düzeltin ve o satırda **Sync**'e basın. Okunamayan bir kaynaktan gelen dokümanlar asla silinmez. ### Dokümanlar kayboldu Ya dosyalar kaynaktan gerçekten gitti (silinen bir dosya bir sonraki çalışmada indeksten kaldırılır), ya da dosya türü seçimini değiştirdiniz, bu yüzden artık indekslenmiyorlar. Başarısız bir senkronizasyon dokümanları **silmez**. ### Bir dosya indekslenmiyor Sırayla kontrol edin: 1. Uzantısı kaynakta seçili mi (varsayılan olarak `.md` ve `.mdx`; `.txt`, `.html`/`.htm`, `.csv`, `.docx` ve `.pdf` opsiyoneldir). 2. Hiç dönüştürülebiliyor mu — OCR yoktur, bu yüzden taranmış ya da şifrelenmiş bir PDF, ya da tamamen görsellerden oluşan bir Word dosyası, yarı indekslenmek yerine kaynağın satırında adıyla reddedilir. 3. Bir nokta-dizininin, `node_modules`, `dist`, `build`, `vendor` ya da `__pycache__`'in içinde değil. 4. `IGNORE_GLOBS` ile eşleşmiyor. 5. İçerik türü dönüşümünden sonra boş değil — boş bir doküman atlanır. 6. Kaynağın dışına işaret eden bir symlink üzerinden erişilmiyor. ### `CHUNK_MAX_TOKENS=… exceeds what … reads` Parçalama bütçesi, gömme modelinin faydalı biçimde okuduğundan daha büyük. Gönderilen varsayılan gönderilen modele uyar, bu yüzden bunu görmek ikisinden birinin kendi başına değiştirildiği anlamına gelir. `CHUNK_MAX_TOKENS`'ı mesajın önerdiği değere ayarlayın ve yeniden indeksleyin. Bu build'in tanımadığı bir model mi çalıştırıyorsunuz? Bağlam penceresini `EMBEDDING_MAX_INPUT_TOKENS`'ta belirtin. Bkz. [Yapılandırma](/tr/docs/configuration/#parçalama). ### İndeksleme yavaş Gömme CPU'ya bağlıdır ve aynı anda bir proje indekslenir. Büyük bir projenin ilk çalışması pahalı olandır; sonraki çalışmalar değişmemiş dosyaları atlar. `EMBEDDING_DTYPE=q8` ya da daha küçük `Xenova/all-MiniLM-L6-v2` modeli ikisi de hızlandırır. --- ## Arama ve istemciler ### Agent bağlanamıyor - URL'deki proje adı tam olarak eşleşmelidir — `Unknown project "…"` eşleşmediği anlamına gelir. - Başka bir makineden, `localhost` yerine sunucunun adresini kullanın, ve güvenlik duvarını kontrol edin. - Tarayıcı tabanlı bir istemcinin origin'inin `ALLOWED_ORIGINS`'te olması gerekir. ### `search_docs` projenin başka bir modelle indekslendiğini söylüyor Sunucunun gömme modeli değişti. Projeyi yeniden indeksleyin — bir sonraki çalışma otomatik olarak tam bir çalışma olur. ### Agent hiçbir şey bulamıyor - Panoda projenin dokümanları ve parçaları olduğunu doğrulayın. - Gerçekten neyin indeklendiğini görmek için `list_topics`'i deneyin. - Daha eksiksiz bir soru sorun: arama hibrittir — anlam ve tam kelime aynı anda — ve bir soru, iki anahtar kelimenin verdiğinden daha fazla sinyal taşır anlam yarısı için. - Hiç sonuç dönmüyorsa, ilgi eşiği onu reddediyor olabilir: `search_docs`, `SEARCH_SCORE_FLOOR`'un (varsayılan `0.82`, varsayılan gömme modeline karşı ölçülen bir kosinüs benzerliği) altında *iyi bir eşleşme yok* yanıtlar. `EMBEDDING_MODEL`'i değiştirdiyseniz, başlangıç logu bunu söyler — gönderilen varsayılanı yeniden kullanmak yerine eşiği kendi gövdenize karşı `npm run eval` ile yeniden ölçün, ya da her projenin kendi eşiğini de kapatmak için `SEARCH_SCORE_FLOOR=0` ayarlayın. Sunucu, gördüğü skorla birlikte kapıda tutulan her sorguyu `info`'da loglar ve kendi eşiğini taşıyan projeleri başlangıç uyarısında adlandırır. - Dokümantasyon hiç başlığı olmayan tek bir devasa dosyaysa, parçalamanın üzerinde çalışacak çok az şeyi vardır — başlık ekleyin. ### Bir agent'a gerçekten dokümante edilmiş bir şey için *iyi eşleşme yok* deniyor Eşik, reddetmemesi gereken bir soruyu reddetti. Sunucunun o sorgu için logladığı skoru, geçerli eşikle karşılaştırın — bir proje kendi eşiğini ayarladıysa onunla, yoksa `SEARCH_SCORE_FLOOR` ile. Sunucunun geri kalanından daha düşük skorlayan bir gövde (referans sayfalarından çok düzyazı), sunucu genelindeki ayarı düşürmektense, sorgu günlüğü panelinde yalnızca o projenin eşiğini düşürmekle genelde daha iyi hizmet görür — orası, uygulamadan önce değişikliği önizler. ### Sonuçlar zayıf - Yerel modelle, `CHUNK_MAX_TOKENS=250` deneyin ve zorla yeniden indeksleyin ([İndeksleme](/tr/docs/indexing/)). - İlgisiz bilgi gövdelerini ayrı projelere bölün. - Gürültüyü (dergiler, changelog'lar, şablonlar) `IGNORE_GLOBS` ile hariç tutun. - Büyük, düzyazı ağırlıklı bir gövde için OpenAI gömmelerini düşünün. ### Yükseltmeden sonra cevaplar uzadı Her alıntı artık eşleşmenin çevresinde daha fazla bağlam için, her iki yanındaki parçayı da taşıyor. `SEARCH_NEIGHBOR_CONTEXT=0` eski, tek parçalı şekli geri getirir ve `SEARCH_MAX_RESULT_CHARS` her durumda tüm yanıtı sınırlar. ### Bir webhook `401 invalid_signature` döndürüyor Depo ayarlarındaki sır, şu anda saklanan sır değil. Onu kaynak diyaloğundan yeniden kopyalayın, ya da **Regenerate**'e basın ve yenisini yapıştırın. Bkz. [Push Webhooks](/tr/docs/push-webhooks/). --- ## Betikler ve admin API'si ### Kendi betiğimden `403 csrf_blocked` Çerezle kimliği doğrulanmış bir yazma bu siteden gelmelidir (`Sec-Fetch-Site`, `Origin`/`Referer`'a geri dönerek) — başka bir origin'den oturum çerezini gönderen bir betik buna takılır. Bunun yerine `Authorization: Bearer $ADMIN_TOKEN`, ya da bir [API token'ı](/tr/docs/admin-api/#api-tokenları) kullanın; bearer istekleri bu kontrolden muaftır. Bkz. [Güvenlik](/tr/docs/security/). ### Yükseltmeden sonra `/api/*`, `401 setup_required` yanıtlıyor Bu örneğin ayarlanmış bir `ADMIN_TOKEN`'ı yoktu ve önceki çalıştırdığı sürümde `/api/*` üzerinde fiilen açıktı. Artık varsayılan olarak kapalı: logdaki kodla `/setup`'ı açın ve ilk hesabı oluşturun, yepyeni bir örnekle aynı şekilde. Zaten orada olan projeler, kaynaklar ve indeksler dokunulmamış kalır. Bkz. [Hesaplar ve İzinler](/tr/docs/accounts-and-permissions/#i̇lk-çalıştırma-kurulum-kodu). --- ## MCP connector'ları ### Bir üye, üyesi olmadığı bir projeyi `/mcp/…`'de okuyor Proje `open` ya da `token required` iken beklenen bir durum: kimseyi adlandırmayan bir kimlik bilgisi, üyeliklere göre değil, moda göre değerlendirilir. Projeyi **MCP access** altında **account required**'a çevirin, endpoint'i üye listesini izlemeye başlar. Bkz. [Hesaplar ve İzinler](/tr/docs/accounts-and-permissions/#hesapların-kapsamadığı-şeyler). ### Bir MCP istemcisi birdenbire `401` yanıtlıyor Proje artık bir kimlik bilgisi gerektiriyor. **MCP access** altında bir token üretin ve `--header "Authorization: Bearer …"` ekleyin (ya da `mcp.json`'da `headers`) — ya da proje **account required** diyorsa, oturum açabilen bir istemciyle yeniden bağlanın, çünkü statik bir token orada reddedilir. ### Bir MCP istemcisi `403 … not a member of this project` yanıtlıyor Kimlik bilgisi sorunsuz ve arkasındaki hesap projede değil. Onu **Members** altına ekleyin, ya da zaten projede olan bir hesapla bağlanın. ### Tarayıcı tabanlı bir connector hiç bağlanamıyor Ya proje `open`/`token required` ve connector'ın göndereceği bir header yok, ya da bu örnekte `MCP_OAUTH=0` ve kullanacağı bir OAuth akışı yok. Bkz. [Yapay Zekâ İstemcilerini Bağlamak](/tr/docs/connecting-ai-clients/). ### Bir connector bağlantısının kesildiğini ve yeniden onaylanması gerektiğini söylüyor Bir parola değişikliğinden sonra, üyeliği kaldırıldıktan sonra, ya da aynı kimlik bilgisi iki kez sunulduktan sonra beklenen bir durum — bu sunucu bunu bir token'ı elinde tutan iki taraf olarak ele alır ve grant'i indirerek yanıtlar. Yalnızca `MCP_OAUTH_REFRESH_TTL_DAYS`'i aşacak kadar kullanılmadan bırakılmış bir connector daha sessiz, farklı bir durumdur: yeniden yetkilendirmesi istenir ve hiçbir şey iptal edilmez. Her iki durumda da onu yeniden onaylayın. ### Bir connector `invalid_scope` bildiriyor Bir OAuth kapsamı istedi. Bu sunucu hiçbirini vermez — hesap destekli bir kimlik bilgisi, hesabının okuyabileceği tam olarak neyse ona ulaşır — bu yüzden istek, kimsenin tanımadığı bir kapsam altında verilmek yerine reddedilir. Sunucu logu isteyen client'ı adlandırır. ### Bir MCP token'ını kaybettim Kurtarılamaz — yalnızca bir hash saklanır. **MCP access** altında iptal edin ve bir tane daha üretin. --- ## Daha fazla ayrıntı almak ```bash docker compose logs -f # follow everything docker compose logs --tail=200 contextator curl -s http://localhost:3444/api/health | jq ``` İstek başına ayrıntılı loglama için, `LOG_LEVEL=debug` ayarlayın ve yeniden başlatın. Yararlı log satırları: `embedding model ready`, `indexing started`, `indexing finished` (sayılarla), `indexing finished with source errors`, `source sync failed`, `mcp session opened` / `closed`. Takılırsanız, şunlarla bir issue açın: `/api/health`'ten sürüm, ilgili log satırları, dahil olan kaynak türü, ve ne olmasını beklediğiniz.