{"record":{"id":"f53f51014b409b9c","repo":"HKUDS/DeepTutor","slug":"graphrag-embedding-dimension-mismatch","errorCode":"graphrag_embedding_dimension_mismatch","errorMessage":"The active embedding model returned {actual} dimensions, but DeepTutor is configured for {configured}. Correct the embedding dimension before indexing with GraphRAG.","messagePattern":"The active embedding model returned (.+?) dimensions, but DeepTutor is configured for (.+?)\\. Correct the embedding dimension before indexing with GraphRAG\\.","errorType":"exception","errorClass":"GraphRagEmbeddingDimensionError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/graphrag/engine.py","lineNumber":257,"sourceCode":"async def _probe_embedding_model_impl(config: Any) -> None:\n    \"\"\"Run one bounded embedding request through GraphRAG's actual client.\"\"\"\n    embedding, expected_dimension = _create_probe_embedding(config)\n    try:\n        response = await embedding.embedding_async(\n            input=[EMBEDDING_PROBE_TEXT],\n            timeout=PROBE_TIMEOUT_SECONDS,\n        )\n    except Exception as error:  # noqa: BLE001 - classified into secret-free metadata\n        classified = classify_embedding_error(error)\n        if classified is not None:\n            raise classified from error\n        raise GraphRagEmbeddingProbeError() from error\n\n    vector = getattr(response, \"first_embedding\", None)\n    if not isinstance(vector, list) or not vector:\n        raise GraphRagEmbeddingResponseError(EMBEDDING_RESPONSE_MESSAGE)\n    if expected_dimension and len(vector) != expected_dimension:\n        raise GraphRagEmbeddingDimensionError(\n            configured=expected_dimension,\n            actual=len(vector),\n        )\n\n\nasync def preflight_embedding(root_dir: Path) -> None:\n    \"\"\"Validate one settings snapshot through GraphRAG's real embedding client.\"\"\"\n    await _run_isolated(lambda: _preflight_embedding_impl(root_dir))\n\n\nasync def preflight_completion(root_dir: Path) -> None:\n    \"\"\"Validate the completion model from the exact persisted settings snapshot.\"\"\"\n    try:\n        await _run_isolated(lambda: _preflight_completion_impl(root_dir))\n    except Exception as error:\n        classified = classify_model_error(error)\n        if classified is not None and classified is not error:\n            raise classified from error","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/graphrag/engine.py#L239-L275","documentation":"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.","triggerScenarios":"Preflight or build probes the active embedding model; the profile says dim=1536 but the endpoint returns e.g. 768 or 3072 dimensions.","commonSituations":"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.","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."],"exampleFix":"# before\nembedding_cfg.model = \"text-embedding-3-large\"; embedding_cfg.dim = 1536\n# after\nembedding_cfg.dim = 3072","handlingStrategy":"validation","validationCode":"vec = (await client.embeddings.create(model=m, input=[\"ping\"])).data[0].embedding\nif cfg.dim and len(vec) != cfg.dim:\n    raise ConfigError(f\"set dim={len(vec)} or switch model\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When swapping embedding models, update dim and reindex the KB.","Run the embedding preflight (it reports mismatches before indexing)."],"tags":["graphrag","embeddings","vector-dimension"],"backgroundTag":"embedding-dimension-mismatch","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}