HKUDS/DeepTutor · error · GraphRagEmbeddingResponseError

graphrag_embedding_incompatible

graphrag_embedding_incompatible

Error message

The active embedding model did not accept or return the vector response required by GraphRAG.

What it means

GraphRagEmbeddingResponseError (code graphrag_embedding_incompatible): the embedding endpoint answered, but response.first_embedding was not a non-empty list — the model did not return the vector format GraphRAG requires.

Source

Thrown at deeptutor/services/rag/pipelines/graphrag/engine.py:255

async def _probe_embedding_model_impl(config: Any) -> None:
    """Run one bounded embedding request through GraphRAG's actual client."""
    embedding, expected_dimension = _create_probe_embedding(config)
    try:
        response = await embedding.embedding_async(
            input=[EMBEDDING_PROBE_TEXT],
            timeout=PROBE_TIMEOUT_SECONDS,
        )
    except Exception as error:  # noqa: BLE001 - classified into secret-free metadata
        classified = classify_embedding_error(error)
        if classified is not None:
            raise classified from error
        raise GraphRagEmbeddingProbeError() from error

    vector = getattr(response, "first_embedding", None)
    if not isinstance(vector, list) or not vector:
        raise GraphRagEmbeddingResponseError(EMBEDDING_RESPONSE_MESSAGE)
    if expected_dimension and len(vector) != expected_dimension:
        raise GraphRagEmbeddingDimensionError(
            configured=expected_dimension,
            actual=len(vector),
        )


async def preflight_embedding(root_dir: Path) -> None:
    """Validate one settings snapshot through GraphRAG's real embedding client."""
    await _run_isolated(lambda: _preflight_embedding_impl(root_dir))


async def preflight_completion(root_dir: Path) -> None:
    """Validate the completion model from the exact persisted settings snapshot."""
    try:
        await _run_isolated(lambda: _preflight_completion_impl(root_dir))
    except Exception as error:
        classified = classify_model_error(error)

View on GitHub (pinned to 3e82f13042)

Solutions

1. Test the endpoint directly with curl POST /embeddings and confirm data[0].embedding is a non-empty array.
2. Use a fully OpenAI-compatible embedding endpoint/model.
3. Check the model name in the embedding profile is valid.

Example fix

curl $ENDPOINT/embeddings -d '{"model":"text-embedding-3-small","input":"hi"}'
# expect {"data":[{"embedding":[...numbers...]}]}

resp = await client.embeddings.create(model=m, input=["ping"])
vec = resp.data[0].embedding
assert isinstance(vec, list) and vec, "endpoint not OpenAI-compatible"

When it happens

Trigger: The embedding probe succeeds at HTTP level but returns empty data, an object instead of an array, or a response shape the adapter can't extract a first embedding from (e.g. native Gemini batch response routed through the OpenAI client).

Common situations: OpenAI-compatible façades with incomplete /embeddings implementations; empty input string being embedded; endpoint returning {"data": []} on certain models; wrong model name silently yielding empty responses.

Related errors

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

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