HKUDS/DeepTutor · error · GraphRagEmbeddingDimensionError

graphrag_embedding_dimension_mismatch

graphrag_embedding_dimension_mismatch

Error message

The active embedding model returned {actual} dimensions, but DeepTutor is configured for {configured}. Correct the embedding dimension before indexing with GraphRAG.

What it means

GraphRagEmbeddingDimensionError (code graphrag_embedding_dimension_mismatch): the probe embedding returned actual dimensions that differ from the configured embedding dimension (embedding_cfg.dim). GraphRAG refuses to index because stored vectors would be inconsistent.

Source

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

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)
        if classified is not None and classified is not error:
            raise classified from error

View on GitHub (pinned to 3e82f13042)

Solutions

Update the embedding profile's dim to match the actual model output (check the probe error's actual value).
Or switch back to the embedding model matching the configured dimension.
Recreate/reindex the GraphRAG KB if it previously indexed with the old dimension.

Example fix

# before
embedding_cfg.model = "text-embedding-3-large"; embedding_cfg.dim = 1536
# after
embedding_cfg.dim = 3072

Defensive patterns

Strategy: validation

Validate before calling

vec = (await client.embeddings.create(model=m, input=["ping"])).data[0].embedding
if cfg.dim and len(vec) != cfg.dim:
    raise ConfigError(f"set dim={len(vec)} or switch model")

Prevention

When swapping embedding models, update dim and reindex the KB.
Run the embedding preflight (it reports mismatches before indexing).

When it happens

Trigger: Preflight or build probes the active embedding model; the profile says dim=1536 but the endpoint returns e.g. 768 or 3072 dimensions.

Common situations: Switching embedding models (text-embedding-ada-002 → text-embedding-3-small/large, or to a local bge model) without updating the dimension; using Matryoshka truncated outputs (dimensions parameter) that differ from the profile; mixing models across a KB rebuild.

Related errors

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