HKUDS/DeepTutor · error · ValueError

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

Error message

Knowledge base '{kb_name}' uses legacy index format and requires reindex before incremental add

What it means

Error "Knowledge base '{kb_name}' uses legacy index format and requires reindex before incremental add" thrown in HKUDS/DeepTutor.

Source

Thrown at deeptutor/knowledge/add_documents.py:187

        self.legacy_rag_storage_dir = self.kb_dir / "rag_storage"
        self.metadata_file = self.kb_dir / "metadata.json"

        # Incremental adds must use the engine DeepTutor has bound to this KB. An
        # explicit rag_provider (from the API, already matched against the KB)
        # 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:

View on GitHub (pinned to 3e82f13042)

When it happens

Trigger: Thrown at deeptutor/knowledge/add_documents.py:187 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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