{"record":{"id":"7211746ae9866bad","repo":"HKUDS/DeepTutor","slug":"knowledge-base-kb-name-uses-legacy-index-forma","errorCode":null,"errorMessage":"Knowledge base '{kb_name}' uses legacy index format and needs reindex before accepting incremental uploads.","messagePattern":"Knowledge base '(.+?)' uses legacy index format and needs reindex before accepting incremental uploads\\.","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":801,"sourceCode":"    \"\"\"Block writes to connected KBs (Obsidian vaults, linked indexes).\n\n    They are read-only pointers to the user's external files — we never write\n    into or re-index them.\n    \"\"\"\n    if is_connected_kb(kb_entry):\n        raise HTTPException(\n            status_code=409,\n            detail=(\n                f\"Knowledge base '{kb_name}' is connected to an external resource and is \"\n                \"read-only. Local file operations and re-indexing are not available for it.\"\n            ),\n        )\n\n\ndef _assert_kb_writable_or_409(kb_name: str, kb_entry: dict) -> None:\n    _assert_not_connected_kb(kb_name, kb_entry)\n    if bool(kb_entry.get(\"needs_reindex\", False)):\n        raise HTTPException(\n            status_code=409,\n            detail=(\n                f\"Knowledge base '{kb_name}' uses legacy index format and needs reindex \"\n                \"before accepting incremental uploads.\"\n            ),\n        )\n\n\ndef _matching_index_is_valid(kb_name: str, matching_version: dict | None) -> bool:\n    \"\"\"Return whether a matching active index can safely satisfy retrieval.\"\"\"\n    if not matching_version:\n        return False\n    try:\n        from deeptutor.services.rag.index_probe import inspect_provider_version\n        from deeptutor.services.rag.pipelines.llamaindex.storage import (\n            validate_storage_embeddings,\n        )\n","sourceCodeStart":783,"sourceCodeEnd":819,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L783-L819","documentation":"Raised by _assert_kb_writable_or_409 when the KB entry carries needs_reindex=True — the KB's index was built with a legacy format and cannot accept incremental uploads until a full reindex migrates it. HTTP 409.","triggerScenarios":"Uploading files, creating folders, moving/deleting files, or syncing a folder on a KB created by an older deeptutor version whose index format changed in an upgrade.","commonSituations":"Upgrading deeptutor across an index-format migration; restoring an old data directory into a new server version.","solutions":["Trigger a full reindex of the KB via the reindex endpoint, which clears needs_reindex","After reindex completes, retry the original write operation","If reindex also fails, check the provider is installed/configured (errors 148-152) and retry"],"exampleFix":"# before\nupload_files(kb='old-kb', ...)  # 409 needs_reindex\n# after\nreindex_knowledge_base('old-kb')\nupload_files(kb='old-kb', ...)","handlingStrategy":"fallback","validationCode":"def kb_accepts_uploads(kb_entry: dict) -> bool:\n    return not kb_entry.get('needs_reindex', False) and not is_connected_kb(kb_entry)","typeGuard":null,"tryCatchPattern":"try: upload_files(kb, files)\nexcept HTTPError as e:\n    if e.response.status_code == 409 and 'needs reindex' in e.response.text():\n        reindex(kb); upload_files(kb, files)","preventionTips":["Run the reindex migration immediately after upgrading deeptutor","Show a 'reindex required' badge on legacy KBs in the UI","Gate upload UI on kb_entry['needs_reindex']"],"tags":["knowledge-base","migration","reindex","legacy-format","http-409"],"backgroundTag":"schema-migration-required","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}