{"record":{"id":"a5093c27ef474048","repo":"HKUDS/DeepTutor","slug":"knowledge-base-not-initialized-self-rag-provider","errorCode":null,"errorMessage":"Knowledge base not initialized ({self.rag_provider}): {kb_name}","messagePattern":"Knowledge base not initialized \\((.+?)\\): (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"deeptutor/knowledge/add_documents.py","lineNumber":192,"sourceCode":"        # wins; otherwise use the shared binding resolver.\n        if rag_provider:\n            self.rag_provider = normalize_provider_name(rag_provider)\n        else:\n            self.rag_provider = self._provider_from_binding()\n\n        has_provider_index = has_ready_provider_index(self.kb_dir, self.rag_provider)\n\n        if (\n            self.rag_provider == DEFAULT_PROVIDER\n            and not has_provider_index\n            and self.legacy_rag_storage_dir.exists()\n        ):\n            raise ValueError(\n                f\"Knowledge base '{kb_name}' uses legacy index format and requires reindex before incremental add\"\n            )\n\n        if not has_provider_index:\n            raise ValueError(f\"Knowledge base not initialized ({self.rag_provider}): {kb_name}\")\n\n        self.api_key = api_key\n        self.base_url = base_url\n        self.progress_tracker = progress_tracker\n\n        self.raw_dir.mkdir(parents=True, exist_ok=True)\n\n    def _provider_from_binding(self) -> str:\n        return resolve_bound_provider(self.base_dir, self.kb_name)\n\n    def _get_file_hash(self, file_path: Path) -> str:\n        sha256_hash = hashlib.sha256()\n        with open(file_path, \"rb\") as f:\n            for byte_block in iter(lambda: f.read(65536), b\"\"):\n                sha256_hash.update(byte_block)\n        return sha256_hash.hexdigest()\n\n    def get_ingested_hashes(self) -> dict[str, str]:","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/knowledge/add_documents.py#L174-L210","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Initialize the KB first: run `deeptutor kb create <name> --doc file.pdf` or run_initialization_task so the provider index is built","Verify the KB was indexed with the same provider currently configured (check metadata.json rag_provider / provider fields)","If the index exists under a different provider, either switch rag_provider back or reindex the KB for the new provider"],"exampleFix":"// before\nadder = DocumentAdder(kb_name=\"my-kb\", ...)  # ValueError: not initialized\n// after\nawait initialize_knowledge_base(kb_name=\"my-kb\", doc_paths=[...])\nadder = DocumentAdder(kb_name=\"my-kb\", ...)","handlingStrategy":"validation","validationCode":"import json\nfrom pathlib import Path\n\ndef kb_has_provider_index(base_dir: Path, kb_name: str, provider: str) -> bool:\n    kb = base_dir / kb_name\n    meta = kb / \"metadata.json\"\n    if not kb.is_dir():\n        return False\n    if meta.exists():\n        m = json.loads(meta.read_text())\n        if m.get(\"rag_provider\", provider) != provider:\n            return False\n    # crude provider-index presence check; adapt to your layout\n    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\")","typeGuard":null,"tryCatchPattern":"try:\n    adder = DocumentAdder(kb_name=kb, ...)\nexcept ValueError as e:\n    if \"not initialized\" in str(e):\n        await initialize_knowledge_base(kb_name=kb, doc_paths=files)  # then retry once\n    else:\n        raise","preventionTips":["Always run the initializer before enabling incremental add for a KB","Keep rag_provider stable across environments; record it in deploy config","Assert metadata.json's provider matches the configured provider at startup"],"tags":["knowledge-base","rag","initialization","deeptutor"],"backgroundTag":"resource-not-initialized","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}