HKUDS/DeepTutor · error · ValueError

Knowledge base not initialized ({self.rag_provider}): {kb_na

Error message

Knowledge base not initialized ({self.rag_provider}): {kb_name}

What it means

Raised by DocumentAdder.__init__ when the named knowledge base has no index for the configured RAG provider (and is not merely legacy-format). The constructor refuses to build an adder against a KB that was never initialized, so any incremental add would have nowhere to write.

Source

Thrown at deeptutor/knowledge/add_documents.py:192

        # wins; otherwise use the shared binding resolver.
        if rag_provider:
            self.rag_provider = normalize_provider_name(rag_provider)
        else:
            self.rag_provider = self._provider_from_binding()

        has_provider_index = has_ready_provider_index(self.kb_dir, self.rag_provider)

        if (
            self.rag_provider == DEFAULT_PROVIDER
            and not has_provider_index
            and self.legacy_rag_storage_dir.exists()
        ):
            raise ValueError(
                f"Knowledge base '{kb_name}' uses legacy index format and requires reindex before incremental add"
            )

        if not has_provider_index:
            raise ValueError(f"Knowledge base not initialized ({self.rag_provider}): {kb_name}")

        self.api_key = api_key
        self.base_url = base_url
        self.progress_tracker = progress_tracker

        self.raw_dir.mkdir(parents=True, exist_ok=True)

    def _provider_from_binding(self) -> str:
        return resolve_bound_provider(self.base_dir, self.kb_name)

    def _get_file_hash(self, file_path: Path) -> str:
        sha256_hash = hashlib.sha256()
        with open(file_path, "rb") as f:
            for byte_block in iter(lambda: f.read(65536), b""):
                sha256_hash.update(byte_block)
        return sha256_hash.hexdigest()

    def get_ingested_hashes(self) -> dict[str, str]:

View on GitHub (pinned to 3e82f13042)

Solutions

1. Initialize the KB first: run `deeptutor kb create <name> --doc file.pdf` or run_initialization_task so the provider index is built
2. Verify the KB was indexed with the same provider currently configured (check metadata.json rag_provider / provider fields)
3. If the index exists under a different provider, either switch rag_provider back or reindex the KB for the new provider

Example fix

// before
adder = DocumentAdder(kb_name="my-kb", ...)  # ValueError: not initialized
// after
await initialize_knowledge_base(kb_name="my-kb", doc_paths=[...])
adder = DocumentAdder(kb_name="my-kb", ...)

import json
from pathlib import Path

def kb_has_provider_index(base_dir: Path, kb_name: str, provider: str) -> bool:
    kb = base_dir / kb_name
    meta = kb / "metadata.json"
    if not kb.is_dir():
        return False
    if meta.exists():
        m = json.loads(meta.read_text())
        if m.get("rag_provider", provider) != provider:
            return False
    # crude provider-index presence check; adapt to your layout
    return any(p.suffix in {".sqlite", ".bin", ".faiss"} or p.is_dir() and any(p.iterdir()) for p in kb.iterdir() if p.name != "raw")

try:
    adder = DocumentAdder(kb_name=kb, ...)
except ValueError as e:
    if "not initialized" in str(e):
        await initialize_knowledge_base(kb_name=kb, doc_paths=files)  # then retry once
    else:
        raise

When it happens

Trigger: Calling add_documents()/DocumentAdder on a KB directory that exists but has no provider index (e.g. created via kb create without documents, or provider switched from lightrag to chroma/qdrant after initial indexing).

Common situations: Switching RAG_PROVIDER between runs, deleting the index folder but keeping raw/, creating a KB from the UI without uploading files, or pointing base_dir at the wrong directory.

Related errors

• No embedding model is configured. Set up the embedding profi
• Knowledge base '{resolved_name}' is not in an error state. U
• Failed to initialize index for KB '{kb_name}' from {len(sour
• Select at most one PageIndex OSS knowledge base per request.
• Archive '{sanitized_filename}' exceeds maximum size limit of

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