{"record":{"id":"eb5db375d8932aec","repo":"HKUDS/DeepTutor","slug":"knowledge-base-resolved-name-is-not-in-an-erro","errorCode":null,"errorMessage":"Knowledge base '{resolved_name}' is not in an error state. Use re-index when you want to rebuild a healthy knowledge base.","messagePattern":"Knowledge base '(.+?)' is not in an error state\\. Use re-index when you want to rebuild a healthy knowledge base\\.","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"warning","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":3016,"sourceCode":"    except Exception as e:\n        logger.error(f\"Failed to start reindex for '{kb_name}': {e}\")\n        raise HTTPException(status_code=500, detail=format_exception_message(e))\n\n\n@router.post(\"/{kb_name}/retry\")\nasync def retry_knowledge_base(\n    kb_name: str,\n    background_tasks: BackgroundTasks,\n):\n    \"\"\"Retry a failed KB initialization/indexing run from its stored raw files.\"\"\"\n    try:\n        manager, resolved_name, _ = _writable_kb(kb_name)\n        kb_entry = _load_kb_entry_or_404(manager, resolved_name)\n        status = str(kb_entry.get(\"status\") or \"\").lower()\n        progress = kb_entry.get(\"progress\") if isinstance(kb_entry.get(\"progress\"), dict) else {}\n        progress_stage = str(progress.get(\"stage\") or \"\").lower()\n        if status != \"error\" and progress_stage != \"error\":\n            raise HTTPException(\n                status_code=409,\n                detail=(\n                    f\"Knowledge base '{resolved_name}' is not in an error state. \"\n                    \"Use re-index when you want to rebuild a healthy knowledge base.\"\n                ),\n            )\n        return await reindex_knowledge_base(resolved_name, background_tasks)\n    except HTTPException:\n        raise\n    except Exception as e:\n        logger.error(f\"Failed to retry KB '{kb_name}': {e}\")\n        raise HTTPException(status_code=500, detail=format_exception_message(e))\n\n\n@router.get(\"/{kb_name}/progress\")\nasync def get_progress(kb_name: str):\n    \"\"\"Get initialization progress for a knowledge base\"\"\"\n    try:","sourceCodeStart":2998,"sourceCodeEnd":3034,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L2998-L3034","documentation":"Thrown (HTTP 409) by the error-recovery endpoint when the target knowledge base is neither in status 'error' nor has progress.stage 'error'. Recovery is only valid for failed indexes; healthy KBs must use the normal re-index flow instead.","triggerScenarios":"POST to /{kb_name}/recover (error-recovery route) for a KB whose entry status is 'ready'/'indexing' and whose progress.stage is not 'error'.","commonSituations":"Frontend offers a 'Fix' button on all KB cards, not just failed ones; a previously failed KB already recovered via a background task and status updated to ready; stale UI showing an error badge.","solutions":["Use the re-index endpoint instead of recovery for a healthy KB","Refresh KB status (GET the KB detail) to confirm it is actually healthy before calling recover","Only surface the recover action in the UI when status or progress.stage is 'error'"],"exampleFix":"// before\nPOST /api/v1/knowledge/my-kb/recover  -> 409 not in an error state\n// after\nPOST /api/v1/knowledge/my-kb/reindex  -> 202  // rebuild a healthy KB","handlingStrategy":"validation","validationCode":"kb = client.get(f'/api/v1/knowledge/{kb_name}').json()\nstate = kb.get('status') or (kb.get('progress') or {}).get('stage')\nif str(state).lower() != 'error':\n    use_reindex_instead_of_recover()","typeGuard":null,"tryCatchPattern":"try:\n    client.post(f'/api/v1/knowledge/{kb}/recover')\nexcept HTTPError as e:\n    if e.response.status_code == 409 and 'not in an error state' in e.response.text:\n        client.post(f'/api/v1/knowledge/{kb}/reindex')\n    else: raise","preventionTips":["Only show a Recover action for KBs with status/progress.stage == error","Refresh KB state immediately before recovery actions","Remember recovery and re-index are distinct flows"],"tags":["knowledge-base","http-409","state-machine","rag"],"backgroundTag":"invalid-state-transition","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}