HKUDS/DeepTutor · error · GraphRagStructuredOutputError

graphrag_model_incompatible

graphrag_model_incompatible

Error message

GraphRAG structured response validation failed.

What it means

GraphRagStructuredOutputError (code graphrag_model_incompatible) raised in _validate_probe_completion: the probe completion call returned, but response.formatted_response is not an instance of the expected pydantic response_model — the structured-output validation failed even though the HTTP call succeeded.

Source

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

        CommunityReportResponse,
    )


async def _validate_probe_completion(completion: Any, response_model: type) -> None:
    """Request and validate one minimal GraphRAG community-report response."""
    response = await completion.completion_async(
        messages=(
            "Return one concise community report for a graph containing one topic named "
            "'compatibility test'. Include a title, summary, one finding with summary and "
            "explanation, a numeric rating, and a rating explanation."
        ),
        response_format=response_model,
        max_tokens=PROBE_MAX_TOKENS,
        stream=False,
        timeout=PROBE_TIMEOUT_SECONDS,
    )
    if not isinstance(getattr(response, "formatted_response", None), response_model):
        raise GraphRagStructuredOutputError("GraphRAG structured response validation failed.")


async def _probe_completion_model_impl(llm_cfg: Any) -> None:
    """Probe a resolved DeepTutor model through the GraphRAG adapter."""
    await _validate_probe_completion(*_create_probe_completion(llm_cfg))


def _failed_probe_result(llm_cfg: Any, error: Exception) -> dict[str, Any]:
    """Classify a probe failure without returning provider messages or credentials."""
    classified = classify_model_error(error)
    if isinstance(
        classified,
        (GraphRagModelIncompatibleError, GraphRagUnsupportedProviderError),
    ):
        status = "incompatible"
        compatible: bool | None = False
    else:
        status = "unverifiable"

View on GitHub (pinned to 3e82f13042)

Solutions

1. Switch to a model with native structured-output support.
2. Raise PROBE_MAX_TOKENS if output is being cut (causing invalid formatted_response).
3. Verify any intermediary proxy forwards response_format and returns choices[0].message content intact.

Example fix

# before: probe against model without response_format support
spec = load_model("my-local-7b")
# after
spec = load_model("deepseek-chat")  # verified structured output

try:
    await preflight_completion(root)
except GraphRagStructuredOutputError as e:
    if e.code == "graphrag_model_incompatible":
        select_structured_output_model()
    raise

When it happens

Trigger: Running the GraphRAG completion preflight (_probe_completion_model_impl / _preflight_completion_impl) against a model that returns unparsable or schema-mismatched output within the probe's max_tokens/timeout budget.

Common situations: Pre-flight checks when setting up a GraphRAG KB with a model that ignores response_format; proxies stripping structured-output fields; models returning wrapped/markdown-fenced JSON.

Related errors

• graphrag_model_output_truncated
• graphrag_model_incompatible
• GraphRAG preflight failed: {failure_details}
• PageIndex OSS preflight failed: {details}
• GraphRAG is not installed. Run `pip install 'deeptutor[graph

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