HKUDS/DeepTutor · error · HTTPException

Requested provider ' ' does not match KB provider ' '. A…

Error message

Requested provider '{requested_provider}' does not match KB provider '{kb_provider}'. A knowledge base is locked to the engine it was created with.

What it means

Provider-lock guard on the KB add/upload route: the caller passed a rag_provider that differs from the provider the KB was created with. A KB is locked to its original engine because its stored index embeddings only match that provider, so mixing batches from another engine is rejected rather than producing an incompatible index.

Solutions

  1. Omit rag_provider so the KB's own provider is used
  2. Create a separate KB with the desired provider for the new documents
  3. Re-index/migrate the KB if a provider change is genuinely intended
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at deeptutor/api/routers/knowledge.py:2571 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/b50ed7fb21b63dba. Report an issue: GitHub.

Appendix: source

Thrown at deeptutor/api/routers/knowledge.py:2571

    is how a caller adding one subtree at a time re-attaches it where it
    belongs instead of piling every batch at the root (#866).
    """
    try:
        manager, kb_name, kb_base_dir = _writable_kb(kb_name)
        requested_provider = None
        if rag_provider is not None and str(rag_provider).strip():
            requested_provider = _validate_registered_provider(rag_provider)

        kb_entry = _load_kb_entry_or_404(manager, kb_name)
        _assert_kb_writable_or_409(kb_name, kb_entry)
        kb_path = manager.get_knowledge_base_path(kb_name)
        raw_dir = kb_path / "raw"
        raw_dir.mkdir(parents=True, exist_ok=True)
        kb_provider = _validate_registered_provider(
            kb_entry.get("rag_provider") or DEFAULT_PROVIDER
        )
        if requested_provider and requested_provider != kb_provider:
            raise HTTPException(
                status_code=400,
                detail=(
                    f"Requested provider '{requested_provider}' does not match KB provider '{kb_provider}'. "
                    "A knowledge base is locked to the engine it was created with."
                ),
            )
        _assert_provider_ready(kb_provider)
        _enforce_provider_formats(kb_provider, files)
        allowed_extensions = FileTypeRouter.get_supported_extensions()
        # ``.zip`` is accepted as an upload container; its members are
        # validated against ``allowed_extensions`` during extraction and the
        # archive itself is never indexed (``safe_extract_zip`` skips ``.zip``).
        upload_extensions = allowed_extensions | {".zip"}
        _validate_upload_batch(files, allowed_extensions=upload_extensions, rel_paths=rel_paths)
        uploaded_files, uploaded_file_paths = await _save_uploaded_files_off_loop(
            files,
            raw_dir,
            allowed_extensions=upload_extensions,

View on GitHub (pinned to 3e82f13042)