{"record":{"id":"17189f6154c84338","repo":"HKUDS/DeepTutor","slug":"failed-to-initialize-index-for-kb-kb-name-from","errorCode":null,"errorMessage":"Failed to initialize index for KB '{kb_name}' from {len(source_files)} file(s)","messagePattern":"Failed to initialize index for KB '(.+?)' from (.+?) file\\(s\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"deeptutor/knowledge/add_documents.py","lineNumber":412,"sourceCode":"    base_dir: str,\n    manager: \"KnowledgeBaseManager\",\n) -> int:\n    \"\"\"Create a fresh index for an empty KB from the given source files.\n\n    Called when :class:`DocumentAdder` rejects an add because the KB has no\n    existing index (it was created empty, e.g. via the no-files fast path or\n    a web/GitHub source sync before any documents were indexed). Uses\n    :meth:`RAGService.initialize` to build the index in one batch, then\n    records file hashes so subsequent incremental adds can detect duplicates.\n    \"\"\"\n    rag_service = RAGService(kb_base_dir=base_dir)\n    kb_dir = Path(base_dir) / kb_name\n    raw_dir = kb_dir / \"raw\"\n    metadata_file = kb_dir / \"metadata.json\"\n\n    success = await rag_service.initialize(kb_name=kb_name, file_paths=source_files)\n    if not success:\n        raise RuntimeError(\n            f\"Failed to initialize index for KB '{kb_name}' from {len(source_files)} file(s)\"\n        )\n\n    # Record hashes so future syncs detect unchanged files.\n    metadata = _read_metadata(metadata_file)\n    hashes = metadata.setdefault(\"file_hashes\", {})\n    for fpath_str in source_files:\n        fpath = Path(fpath_str)\n        sha = hashlib.sha256()\n        with open(fpath, \"rb\") as fh:\n            for block in iter(lambda: fh.read(65536), b\"\"):\n                sha.update(block)\n        hashes[_raw_hash_key(fpath, raw_dir)] = sha.hexdigest()\n    metadata[\"rag_provider\"] = rag_service._resolve_provider(kb_name)\n    metadata[\"needs_reindex\"] = False\n    ts = datetime.now().strftime(\"%Y-%m-%d %H:%M:%S\")\n    metadata[\"last_updated\"] = ts\n    metadata[\"last_indexed_at\"] = ts","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/knowledge/add_documents.py#L394-L430","documentation":"_bootstrap_index_from_files calls rag_service.initialize() to build an index from the listed source files; when the service reports failure (returns falsy) this RuntimeError propagates out of add_documents. It means the underlying RAG provider failed to create/ingest the index (embedding errors, provider downtime, bad file formats).","triggerScenarios":"Calling add_documents() on a KB whose provider index is missing, where rag_service.initialize(kb_name, file_paths=source_files) fails — bad/missing embedding API key, unreachable vector store, unreadable source files, or empty file list.","commonSituations":"Expired or missing OPENAI_API_KEY/embedding credentials, vector DB (Chroma/Qdrant/LightRAG server) not running, corrupted raw/ files after a partial copy, disk-full during index write.","solutions":["Check embedding provider credentials and connectivity (API key set, embedding endpoint reachable)","Ensure the vector store / RAG backend the KB uses is running and writable","Inspect rag_service.initialize logs for the underlying provider error and fix that (bad file, OOM, disk space)","Retry add_documents once the provider issue is fixed; if the index is half-built, wipe the KB index directory and re-initialize"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"async def can_initialize(rag_service, kb_name: str, files: list[str]) -> bool:\n    return bool(files) and all(Path(f).is_file() for f in files)","typeGuard":null,"tryCatchPattern":"try:\n    await add_documents(kb, docs_dir)\nexcept RuntimeError as e:\n    if \"Failed to initialize index\" in str(e):\n        log.error(\"index bootstrap failed; check embedding creds/backend, then retry\")\n        await asyncio.sleep(backoff); await add_documents(kb, docs_dir)  # bounded retry\n    else:\n        raise","preventionTips":["Health-check the embedding provider and vector store before sync jobs","Run add_documents behind a job queue with retry/backoff","Alert on bootstrap failures so half-built indexes get wiped and rebuilt"],"tags":["rag","index-build","embedding","deeptutor"],"backgroundTag":"backend-service-initialization-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}