{"record":{"id":"d4dcb90c09ffcb4b","repo":"HKUDS/DeepTutor","slug":"graphrag-model-incompatible","errorCode":"graphrag_model_incompatible","errorMessage":"The model did not accept or return the structured output required by GraphRAG.","messagePattern":"The model did not accept or return the structured output required by GraphRAG\\.","errorType":"exception","errorClass":"GraphRagStructuredOutputError","httpStatus":null,"severity":"error","filePath":"deeptutor/services/rag/pipelines/graphrag/completion_adapter.py","lineNumber":128,"sourceCode":"    fallback[\"messages\"] = _messages_with_schema(fallback[\"messages\"], response_format)\n    fallback.pop(\"response_format\", None)\n    return fallback\n\n\ndef _format_response(response: Any, response_format: type[BaseModel]) -> Any:\n    from graphrag_llm.utils import structure_completion_response\n\n    try:\n        response.formatted_response = structure_completion_response(\n            response.content,\n            response_format,\n        )\n    except (json.JSONDecodeError, TypeError, ValidationError, ValueError) as error:\n        choices = getattr(response, \"choices\", None)\n        finish_reason = getattr(choices[0], \"finish_reason\", None) if choices else None\n        if finish_reason in {\"length\", \"max_tokens\"}:\n            raise GraphRagStructuredOutputTruncatedError(MODEL_OUTPUT_TRUNCATED_MESSAGE) from error\n        raise GraphRagStructuredOutputError(MODEL_INCOMPATIBLE_MESSAGE) from error\n    return response\n\n\ndef _native_validation_error(error: BaseException) -> bool:\n    return isinstance(error, (json.JSONDecodeError, ValidationError))\n\n\ndef _fallback_sync(instance: Any, kwargs: dict[str, Any], response_format: type[BaseModel]) -> Any:\n    fallback = _format_fallback_kwargs(kwargs, response_format)\n    if fallback.get(\"stream\"):\n        raise ValueError(\"response_format is not supported for streaming completions.\")\n    messages = fallback.pop(\"messages\")\n    if isinstance(messages, str):\n        messages = [{\"role\": \"user\", \"content\": messages}]\n    request_metrics = fallback.pop(\"metrics\", None) or {}\n    if not instance._track_metrics:\n        request_metrics = None\n    try:","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/services/rag/pipelines/graphrag/completion_adapter.py#L110-L146","documentation":"GraphRagStructuredOutputError (code graphrag_model_incompatible): the model's response to a GraphRAG structured-output request could not be parsed/validated (json.JSONDecodeError, TypeError, pydantic ValidationError, ValueError) and truncation was not the cause. The model either ignored the schema or returned malformed JSON.","triggerScenarios":"A chat model that doesn't support response_format / structured outputs returns prose or schema-violating JSON during GraphRAG indexing or the probe (_probe_completion_model_impl / _fallback_sync / _fallback_async).","commonSituations":"Using an OpenAI-compatible proxy or local model (llama.cpp, vLLM, older TGI) that ignores json_schema response_format; models that wrap JSON in markdown fences; mismatched pydantic schema expectations across GraphRAG versions.","solutions":["Switch the active chat model to one with verified structured-output support (recent OpenAI/Anthropic/DeepSeek models).","Enable/force JSON mode on the provider endpoint.","Update the model or serving stack so response_format is honored.","If using a proxy, verify it forwards the response_format field."],"exampleFix":"# before: model ignores response_format\nmodel = \"local-mistral-7b\"\n# after\nmodel = \"gpt-4o\"  # or another model with native structured output","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await build(root)\nexcept GraphRagStructuredOutputError as e:\n    if e.code == \"graphrag_model_incompatible\":\n        switch_to_structured_output_model()\n    raise","preventionTips":["Keep a known-good chat model profile for GraphRAG separate from experimental ones.","Run preflight_completion before indexing."],"tags":["graphrag","structured-output","llm","schema-validation"],"backgroundTag":"llm-structured-output-invalid","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}