HKUDS/DeepTutor · error · RuntimeError

Failed to initialize index for KB '{kb_name}' from {len(sour

Error message

Failed to initialize index for KB '{kb_name}' from {len(source_files)} file(s)

What it means

_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).

Source

Thrown at deeptutor/knowledge/add_documents.py:412

    base_dir: str,
    manager: "KnowledgeBaseManager",
) -> int:
    """Create a fresh index for an empty KB from the given source files.

    Called when :class:`DocumentAdder` rejects an add because the KB has no
    existing index (it was created empty, e.g. via the no-files fast path or
    a web/GitHub source sync before any documents were indexed). Uses
    :meth:`RAGService.initialize` to build the index in one batch, then
    records file hashes so subsequent incremental adds can detect duplicates.
    """
    rag_service = RAGService(kb_base_dir=base_dir)
    kb_dir = Path(base_dir) / kb_name
    raw_dir = kb_dir / "raw"
    metadata_file = kb_dir / "metadata.json"

    success = await rag_service.initialize(kb_name=kb_name, file_paths=source_files)
    if not success:
        raise RuntimeError(
            f"Failed to initialize index for KB '{kb_name}' from {len(source_files)} file(s)"
        )

    # Record hashes so future syncs detect unchanged files.
    metadata = _read_metadata(metadata_file)
    hashes = metadata.setdefault("file_hashes", {})
    for fpath_str in source_files:
        fpath = Path(fpath_str)
        sha = hashlib.sha256()
        with open(fpath, "rb") as fh:
            for block in iter(lambda: fh.read(65536), b""):
                sha.update(block)
        hashes[_raw_hash_key(fpath, raw_dir)] = sha.hexdigest()
    metadata["rag_provider"] = rag_service._resolve_provider(kb_name)
    metadata["needs_reindex"] = False
    ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    metadata["last_updated"] = ts
    metadata["last_indexed_at"] = ts

View on GitHub (pinned to 3e82f13042)

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

Defensive patterns

Strategy: retry

Validate before calling

async def can_initialize(rag_service, kb_name: str, files: list[str]) -> bool:
    return bool(files) and all(Path(f).is_file() for f in files)

Try / catch

try:
    await add_documents(kb, docs_dir)
except RuntimeError as e:
    if "Failed to initialize index" in str(e):
        log.error("index bootstrap failed; check embedding creds/backend, then retry")
        await asyncio.sleep(backoff); await add_documents(kb, docs_dir)  # bounded retry
    else:
        raise

Prevention

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

When it happens

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

Common situations: 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.

Related errors

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