HKUDS/DeepTutor · error · GraphRagEmbeddingProviderUnsupportedError

graphrag_embedding_provider_unsupported

graphrag_embedding_provider_unsupported

Error message

GraphRAG currently requires an OpenAI-compatible embedding endpoint. The active embedding provider uses a native transport; choose its OpenAI-compatible endpoint or another embedding profile.

What it means

GraphRagEmbeddingProviderUnsupportedError (code graphrag_embedding_provider_unsupported): raised by ensure_graphrag_embedding_transport when the active embedding provider's canonical binding is not in OPENAI_COMPATIBLE_EMBEDDING_BINDINGS — GraphRAG can only call OpenAI-compatible embedding endpoints, not DeepTutor's native transports.

Source

Thrown at deeptutor/services/rag/pipelines/graphrag/config.py:151

    if parsed.query or parsed.fragment:
        return value

    path = parsed.path.rstrip("/")
    if not path.endswith("/embeddings"):
        return value

    api_path = path[: -len("/embeddings")] or "/"
    return urlunsplit(parsed._replace(path=api_path))


def ensure_graphrag_embedding_transport(
    binding: str | None,
    endpoint: str | None,
) -> None:
    """Reject native embedding transports that GraphRAG cannot call safely."""
    provider = canonical_embedding_provider_name(binding)
    if provider not in OPENAI_COMPATIBLE_EMBEDDING_BINDINGS:
        raise GraphRagEmbeddingProviderUnsupportedError()
    # Gemini can use either DeepTutor's native ``batchEmbedContents`` adapter
    # or its legacy OpenAI-compatible endpoint. GraphRAG only supports the
    # latter; a provider name alone is no longer enough after Gemini 2 support.
    if provider == "gemini" and not urlsplit(str(endpoint or "")).path.rstrip("/").endswith(
        "/embeddings"
    ):
        raise GraphRagEmbeddingProviderUnsupportedError()


@dataclass(frozen=True)
class GraphRagQueryConfig:
    """Query-time knobs read from the persisted ``graphrag.json`` slice."""

    response_type: str = "Multiple Paragraphs"
    community_level: int = 2
    dynamic_community_selection: bool = False

View on GitHub (pinned to 3e82f13042)

Solutions

1. Switch the active embedding profile to an OpenAI-compatible provider (OpenAI, DeepSeek, or any /v1/embeddings-compatible endpoint).
2. If using Gemini, select its legacy OpenAI-compatible endpoint profile (path ending in /embeddings).
3. Configure a separate embedding profile specifically for GraphRAG KBs.

Example fix

# before
embedding binding = "gemini_native"
# after
embedding binding = "openai"  # url: https://api.openai.com/v1/embeddings

from deeptutor.services.rag.pipelines.graphrag.config import OPENAI_COMPATIBLE_EMBEDDING_BINDINGS
if canonical_embedding_provider_name(cfg.binding) not in OPENAI_COMPATIBLE_EMBEDDING_BINDINGS:
    raise ConfigError("pick an OpenAI-compatible embedding profile")

When it happens

Trigger: build_settings runs with an embedding profile whose binding is a native transport (e.g. Gemini batchEmbedContents, a non-OpenAI-compatible local server) while creating or updating a GraphRAG knowledge base.

Common situations: Default embedding profile is Gemini-native or a custom binding after Gemini 2 support was added; switching embedding providers without checking GraphRAG compatibility.

Related errors

• No active embedding model. Configure one under Settings → Ca
• No active embedding model with a known dimension. Configure
• graphrag_embedding_probe_failed
• graphrag_embedding_incompatible
• graphrag_embedding_dimension_mismatch

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