{"record":{"id":"6da3100899f745c3","repo":"HKUDS/DeepTutor","slug":"graphrag-embedding-probe-failed","errorCode":"graphrag_embedding_probe_failed","errorMessage":"GraphRAG embedding compatibility could not be verified because of an internal error.","messagePattern":"GraphRAG embedding compatibility could not be verified because of an internal error\\.","errorType":"exception","errorClass":"GraphRagEmbeddingProbeError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/graphrag/engine.py","lineNumber":251,"sourceCode":"    model_id = config.embed_text.embedding_model_id\n    model_config = config.embedding_models[model_id]\n    expected_dimension = int(config.vector_store.vector_size or 0)\n    return create_embedding(model_config), expected_dimension\n\n\nasync 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.\"\"\"","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/graphrag/engine.py#L233-L269","documentation":"GraphRagEmbeddingProbeError (code graphrag_embedding_probe_failed): the embedding probe call raised an exception that classify_embedding_error could not map to a known category (dimension mismatch, auth, response format), so it is wrapped as an internal, secret-free probe failure.","triggerScenarios":"_probe_embedding_model_impl makes a test embedding request during preflight or build and the underlying client throws an unexpected exception type (network glitch, unexpected SDK error, timeout not in the classified set).","commonSituations":"Transient network errors to the embedding endpoint; SDK version changes introducing new exception types; misconfigured TLS/proxy environments producing unusual errors.","solutions":["Retry the preflight/build — transient causes often clear.","Check the chained `from error` cause in logs (the original exception is preserved) to identify the real problem.","Verify the embedding endpoint URL, API key, and network reachability.","Update DeepTutor if classify_embedding_error misses a newly common exception class."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await preflight_embedding(root)\nexcept GraphRagEmbeddingProbeError as e:\n    if not retry_with_backoff(2):\n        log.exception(\"cause\", exc_info=e.__cause__)\n        raise","preventionTips":["Log the chained __cause__ — the real failure is preserved there.","Keep embedding endpoint credentials/URLs validated at profile save time."],"tags":["graphrag","embeddings","probe","network"],"backgroundTag":"embedding-probe-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}