HKUDS/DeepTutor · error · HTTPException

Knowledge base '{kb_name}' uses legacy index format and need

Error message

Knowledge base '{kb_name}' uses legacy index format and needs reindex before accepting incremental uploads.

What it means

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.

Source

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

    """Block writes to connected KBs (Obsidian vaults, linked indexes).

    They are read-only pointers to the user's external files — we never write
    into or re-index them.
    """
    if is_connected_kb(kb_entry):
        raise HTTPException(
            status_code=409,
            detail=(
                f"Knowledge base '{kb_name}' is connected to an external resource and is "
                "read-only. Local file operations and re-indexing are not available for it."
            ),
        )


def _assert_kb_writable_or_409(kb_name: str, kb_entry: dict) -> None:
    _assert_not_connected_kb(kb_name, kb_entry)
    if bool(kb_entry.get("needs_reindex", False)):
        raise HTTPException(
            status_code=409,
            detail=(
                f"Knowledge base '{kb_name}' uses legacy index format and needs reindex "
                "before accepting incremental uploads."
            ),
        )


def _matching_index_is_valid(kb_name: str, matching_version: dict | None) -> bool:
    """Return whether a matching active index can safely satisfy retrieval."""
    if not matching_version:
        return False
    try:
        from deeptutor.services.rag.index_probe import inspect_provider_version
        from deeptutor.services.rag.pipelines.llamaindex.storage import (
            validate_storage_embeddings,
        )

View on GitHub (pinned to 3e82f13042)

Solutions

1. Trigger a full reindex of the KB via the reindex endpoint, which clears needs_reindex
2. After reindex completes, retry the original write operation
3. If reindex also fails, check the provider is installed/configured (errors 148-152) and retry

Example fix

# before
upload_files(kb='old-kb', ...)  # 409 needs_reindex
# after
reindex_knowledge_base('old-kb')
upload_files(kb='old-kb', ...)

def kb_accepts_uploads(kb_entry: dict) -> bool:
    return not kb_entry.get('needs_reindex', False) and not is_connected_kb(kb_entry)

try: upload_files(kb, files)
except HTTPError as e:
    if e.response.status_code == 409 and 'needs reindex' in e.response.text():
        reindex(kb); upload_files(kb, files)

When it happens

Trigger: 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.

Common situations: Upgrading deeptutor across an index-format migration; restoring an old data directory into a new server version.

Related errors

• Knowledge base '{kb_name}' is connected to an external resou
• No embedding model is configured. Set up the embedding profi
• Knowledge base '{resolved_name}' is not in an error state. U
• VisualReviewAgent prompts are not configured.
• Archive '{sanitized_filename}' exceeds maximum size limit of

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