HKUDS/DeepTutor · error · GraphRagEmbeddingProbeError

graphrag_embedding_probe_failed

graphrag_embedding_probe_failed

Error message

GraphRAG embedding compatibility could not be verified because of an internal error.

What it means

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.

Source

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

    model_id = config.embed_text.embedding_model_id
    model_config = config.embedding_models[model_id]
    expected_dimension = int(config.vector_store.vector_size or 0)
    return create_embedding(model_config), expected_dimension


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."""

View on GitHub (pinned to 3e82f13042)

Solutions

1. Retry the preflight/build — transient causes often clear.
2. Check the chained `from error` cause in logs (the original exception is preserved) to identify the real problem.
3. Verify the embedding endpoint URL, API key, and network reachability.
4. Update DeepTutor if classify_embedding_error misses a newly common exception class.

try:
    await preflight_embedding(root)
except GraphRagEmbeddingProbeError as e:
    if not retry_with_backoff(2):
        log.exception("cause", exc_info=e.__cause__)
        raise

When it happens

Trigger: _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).

Common situations: Transient network errors to the embedding endpoint; SDK version changes introducing new exception types; misconfigured TLS/proxy environments producing unusual errors.

Related errors

• OpenAI SDK connection error: {exc}
• graphrag_embedding_provider_unsupported
• No active embedding model. Configure one under Settings → Ca
• No active embedding model with a known dimension. Configure
• graphrag_embedding_incompatible

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