Sorun Giderme — Contextator

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.

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.

`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. 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 -- <kullanıcı-adı>.

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.

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ğı.

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ğı.

`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.

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.

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’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; <ad>: <neden> 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:

Uzantısı kaynakta seçili mi (varsayılan olarak .md ve .mdx; .txt, .html/.htm, .csv, .docx ve .pdf opsiyoneldir).
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.
Bir nokta-dizininin, node_modules, dist, build, vendor ya da __pycache__’in içinde değil.
IGNORE_GLOBS ile eşleşmiyor.
İçerik türü dönüşümünden sonra boş değil — boş bir doküman atlanır.
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.

İ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).
İ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.

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’ı kullanın; bearer istekleri bu kontrolden muaftır. Bkz. Güvenlik.

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.

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.

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.

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

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.

Başlangıç

Konteyner sürekli yeniden başlıyor

The database was created with EMBEDDING_DIMENSIONS=… but the current config says …