HKUDS/DeepTutor · warning · HTTPException

Knowledge base '{resolved_name}' is not in an error state. U

Error message

Knowledge base '{resolved_name}' is not in an error state. Use re-index when you want to rebuild a healthy knowledge base.

What it means

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.

Source

Thrown at deeptutor/api/routers/knowledge.py:3016

    except Exception as e:
        logger.error(f"Failed to start reindex for '{kb_name}': {e}")
        raise HTTPException(status_code=500, detail=format_exception_message(e))


@router.post("/{kb_name}/retry")
async def retry_knowledge_base(
    kb_name: str,
    background_tasks: BackgroundTasks,
):
    """Retry a failed KB initialization/indexing run from its stored raw files."""
    try:
        manager, resolved_name, _ = _writable_kb(kb_name)
        kb_entry = _load_kb_entry_or_404(manager, resolved_name)
        status = str(kb_entry.get("status") or "").lower()
        progress = kb_entry.get("progress") if isinstance(kb_entry.get("progress"), dict) else {}
        progress_stage = str(progress.get("stage") or "").lower()
        if status != "error" and progress_stage != "error":
            raise HTTPException(
                status_code=409,
                detail=(
                    f"Knowledge base '{resolved_name}' is not in an error state. "
                    "Use re-index when you want to rebuild a healthy knowledge base."
                ),
            )
        return await reindex_knowledge_base(resolved_name, background_tasks)
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Failed to retry KB '{kb_name}': {e}")
        raise HTTPException(status_code=500, detail=format_exception_message(e))


@router.get("/{kb_name}/progress")
async def get_progress(kb_name: str):
    """Get initialization progress for a knowledge base"""
    try:

View on GitHub (pinned to 3e82f13042)

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'

Example fix

// before
POST /api/v1/knowledge/my-kb/recover  -> 409 not in an error state
// after
POST /api/v1/knowledge/my-kb/reindex  -> 202  // rebuild a healthy KB

Defensive patterns

Strategy: validation

Validate before calling

kb = client.get(f'/api/v1/knowledge/{kb_name}').json()
state = kb.get('status') or (kb.get('progress') or {}).get('stage')
if str(state).lower() != 'error':
    use_reindex_instead_of_recover()

Try / catch

try:
    client.post(f'/api/v1/knowledge/{kb}/recover')
except HTTPError as e:
    if e.response.status_code == 409 and 'not in an error state' in e.response.text:
        client.post(f'/api/v1/knowledge/{kb}/reindex')
    else: raise

Prevention

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

When it happens

Trigger: POST to /{kb_name}/recover (error-recovery route) for a KB whose entry status is 'ready'/'indexing' and whose progress.stage is not 'error'.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/eb5db375d8932aec. Report an issue: GitHub.