HKUDS/DeepTutor · error · HTTPException

Knowledge base ' ' already has a ready index. Provider…

Error message

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.

What it means

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.

Solutions

1. Run the explicit re-index/migration flow for the KB, then apply the provider change
2. If no provider switch was intended, resend the config keeping the current rag_provider
3. Delete the existing index (or the KB) if a clean rebuild under the new provider is desired, then retry

When it happens

Trigger: Thrown at deeptutor/api/routers/knowledge.py:1629 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

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

@router.put("/{kb_name}/config")
async def update_kb_config(kb_name: str, config: dict):
    """Update configuration for a specific knowledge base."""
    try:
        from deeptutor.services.config import get_kb_config_service
        from deeptutor.services.rag.index_probe import has_ready_provider_index

        config = dict(config or {})
        if "rag_provider" in config:
            requested_provider = _validate_registered_provider(config.get("rag_provider"))
            service = get_kb_config_service()
            current_config = service.get_kb_config(kb_name)
            current_provider = _validate_registered_provider(
                current_config.get("rag_provider") or DEFAULT_PROVIDER
            )
            if requested_provider != current_provider:
                kb_dir = _current_kb_base_dir() / kb_name
                if kb_dir.exists() and has_ready_provider_index(kb_dir, current_provider):
                    raise HTTPException(
                        status_code=409,
                        detail=(
                            f"Knowledge base '{kb_name}' already has a ready "
                            f"{current_provider} index. Provider changes require "
                            "an explicit re-index/migration instead of a silent config edit."
                        ),
                    )
                config["needs_reindex"] = True
                config.setdefault("status", "needs_reindex")
                config["progress"] = {
                    "stage": "needs_reindex",
                    "message": (
                        f"Provider changed from {current_provider} to {requested_provider}; "
                        "re-index this knowledge base before use."
                    ),
                    "percent": 0,
                    "timestamp": datetime.now().isoformat(),
                }

View on GitHub (pinned to 3e82f13042)