{"record":{"id":"fa1f5c2d1d624ae0","repo":"HKUDS/DeepTutor","slug":"knowledge-base-kb-name-already-has-a-ready-cu","errorCode":null,"errorMessage":"Knowledge base '{kb_name}' already has a ready {current_provider} index. Provider changes require an explicit re-index/migration instead of a silent config edit.","messagePattern":"Knowledge base '(.+?)' already has a ready (.+?) index\\. Provider changes require an explicit re-index/migration instead of a silent config edit\\.","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":1629,"sourceCode":"@router.put(\"/{kb_name}/config\")\nasync def update_kb_config(kb_name: str, config: dict):\n    \"\"\"Update configuration for a specific knowledge base.\"\"\"\n    try:\n        from deeptutor.services.config import get_kb_config_service\n        from deeptutor.services.rag.index_probe import has_ready_provider_index\n\n        config = dict(config or {})\n        if \"rag_provider\" in config:\n            requested_provider = _validate_registered_provider(config.get(\"rag_provider\"))\n            service = get_kb_config_service()\n            current_config = service.get_kb_config(kb_name)\n            current_provider = _validate_registered_provider(\n                current_config.get(\"rag_provider\") or DEFAULT_PROVIDER\n            )\n            if requested_provider != current_provider:\n                kb_dir = _current_kb_base_dir() / kb_name\n                if kb_dir.exists() and has_ready_provider_index(kb_dir, current_provider):\n                    raise HTTPException(\n                        status_code=409,\n                        detail=(\n                            f\"Knowledge base '{kb_name}' already has a ready \"\n                            f\"{current_provider} index. Provider changes require \"\n                            \"an explicit re-index/migration instead of a silent config edit.\"\n                        ),\n                    )\n                config[\"needs_reindex\"] = True\n                config.setdefault(\"status\", \"needs_reindex\")\n                config[\"progress\"] = {\n                    \"stage\": \"needs_reindex\",\n                    \"message\": (\n                        f\"Provider changed from {current_provider} to {requested_provider}; \"\n                        \"re-index this knowledge base before use.\"\n                    ),\n                    \"percent\": 0,\n                    \"timestamp\": datetime.now().isoformat(),\n                }","sourceCodeStart":1611,"sourceCodeEnd":1647,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L1611-L1647","documentation":"Conflict guard (409) in PUT /knowledge-bases/{kb_name}/config: the request tries to change rag_provider while the KB directory still holds a ready, usable index built by the current provider. Silently editing the config would leave retrieval pointing at an engine whose index no longer matches, so the endpoint refuses and demands an explicit re-index/migration. When no ready index exists, the change is allowed and the config is flagged needs_reindex instead.","triggerScenarios":"Thrown at deeptutor/api/routers/knowledge.py:1629 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Run the explicit re-index/migration flow for the KB, then apply the provider change","If no provider switch was intended, resend the config keeping the current rag_provider","Delete the existing index (or the KB) if a clean rebuild under the new provider is desired, then retry"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","contentChangedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}