MESA Core · v0.9.3

Sorun giderme

v0.9.3 kaynak: docs/RUNBOOK.md

Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.

Hatanın hangi aşamada olduğunu bulun#

Başlatma kontrolünü ve anahtar gerektiren hazır olma kontrolünü ayrı çalıştırın. Vektör veya çizge aramasının kullanılabildiğini söylemeden önce sistemin yetenek yanıtına bakın. Combined çalışma, modeller kapalıyken veri alımını ve BM25 aramasını destekler. 503 canonical_processing_unavailable hatası combined tüketicinin kullanılamadığını gösterir; HTTP 202 aldıysanız da işlem bitene kadar durumu izleyin. Tekrarlanan hatalarda işleme hattının ve arama görünümlerinin işlem kayıtlarını inceleyin.

Güvenlik denetimlerini aşmayın#

Genel bir çözüm olarak kilit dosyasını silmeyin, üst erişim alanı denetimini atlamayın veya anlam doğrulamasında reddedilen işi yeniden yürütmeyin. Doğru adımlar için aşağıdaki kaynağa ve işletim rehberine bakın. API ve sürüm sınırları belgeleri hata yanıtlarını yorumlamayı kolaylaştırır.

Şemalar

UML · Durum makinesiBir değişikliğin QUEUED’dan son duruma yolu
QUEUEDRUNNINGEXTRACTEDVALIDATEDPROJECTINGCOMMITTEDDLQRETRY_PENDINGREJECTEDBLOCKEDROLLED_BACK işçi alırbilgi veya kaynakkontrol geçtiSQL yazıldıadımlar tamam geçici hata (herhangi adım) [doğrulama reddeder] yeniden dene deneme hakkı bitti yeniden kuyruk geri alma[temizlik bitti] geri alma [temizlik bitmedi] REJECTED denetim kaynağını tutar, arama verisi oluşturmaz.

COMMITTED, gerekli adımların tamamlandığını gösterir; kapalı vektör/çizge adımları SKIPPED olabilir. Yeniden denemeler sınırlıdır; sonuçlanmayan iş, biri yeniden kuyruğa alana kadar hata kuyruğunda (DLQ) bekler. Hata gizlenmez, görünür kalır.

Tüm şemalar ve gerekçeleri: Mimari →

Dayanak kaynaklar
Kaynak belgedeki ilgili bölümler

Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.

Troubleshooting#

Capture version/commit, runtime profile, content-free health, mutation/operation

IDs and error class. Never include keys, claim tokens or full source/query text.

SymptomCheckSafe response
Missing runtime profile/rootExplicit environment and CLI helpUse a dedicated writable root, never repo/home/filesystem root
401Key registry, active principal, key rotationRe-provision/reload authorized credentials; do not disable auth
403/session conflictACL, session principal and dataset/agent bindingGrant intended scope offline; start a properly scoped session
Insert 422Required title/IDs, character bounds and contentCompare actual OpenAPI schema; keep exact source
Insert 409Frozen revision, identity/idempotency conflictReuse exact retry payload or create a new revision
Embedding 409/mismatchFull provider/model/revision/dimension/normalization identityFollow offline migration/rebuild; equal dimension is not equal space
503 vector_backend_unavailableProvider availability and operational identityRestore the selected provider; no silent model switch
503 graph_backend_unavailableHealth, timeout, Kùzu schema/parityDiagnose query/backend and bounded traversal; do not advertise complete results
503 maintenance_pendingActive/retryable rebuild statusFollow rebuild runbook; no manual lease/queue deletion
Mutation stalls or enters DLQProjection predecessor, fenced claim, provider errorsRepair cause, then authorized replay if state permits
Semantic rejectionRejection reason and validation policyTreat as terminal; generic replay returns NON_REPLAYABLE
Cleanup BLOCKEDStore availability and shared ownershipPreserve evidence, repair store, run supported recovery
Readiness 503Worker liveness, thresholds, canonical backlogResolve health; process alive does not mean ready
FTS/parity errorMatching Alembic head and checksummed backupStop writers and rehearse recovery into a new root
Old Kùzu timestamp/schema errorRelease code and offline schema migrationUpgrade/rehearse from backups; do not issue ad hoc ALTER or wipe
Growing RSS/diskLance fragments/versions, queues and retained generationsMeasure representative workload; apply supported maintenance, reserve capacity

Inspect /v4/capability before assuming semantic/graph availability. A model-disabled

profile intentionally lacks semantic generation. wait_until_committed() can

return failed terminal states; inspect state explicitly.

CLI --help, configuration, API,

operations and migration describe supported

interfaces. Avoid raw SQL edits, in-place restore, forced queue completion and

unbounded retries. Real provider or production-size evidence unavailable in an

audit must remain NOT EXECUTED, never converted to a simulated success.