{
  "id": "llm/structured-output-json-mode-returns-unexpected-field",
  "signature": "json.decoder.JSONDecodeError: Expecting property name at position N",
  "signature_zh": "结构化输出 JSON 模式返回意外字段：输出包含模式中未定义的键",
  "regex": "Unexpected field|extra.*keys.*not allowed|JSON.*schema.*violation",
  "domain": "llm",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "When using JSON mode (response_format={type: 'json_object'}), the LLM generates a JSON object with keys not present in the requested schema, causing downstream parsing to fail or validation to reject the output.",
  "root_cause_type": "generic",
  "root_cause_zh": "使用 JSON 模式（response_format={type: 'json_object'}）时，LLM 生成包含请求模式中不存在的键的 JSON 对象，导致下游解析失败或验证拒绝输出。",
  "versions": [
    {
      "version": "openai>=1.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "pydantic>=2.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "python>=3.9",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Add more examples to the system prompt showing the exact JSON structure",
      "why_fails": "LLMs may still hallucinate extra fields even with examples; examples reduce but don't eliminate the issue.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a stronger model like GPT-4 instead of GPT-3.5",
      "why_fails": "While GPT-4 is more reliable, it can still produce extra fields in JSON mode, especially with complex schemas.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Use Pydantic's 'extra' parameter set to 'forbid' to reject extra fields, and re-prompt the LLM on failure.",
      "success_rate": 0.9,
      "how": "Use Pydantic's 'extra' parameter set to 'forbid' to reject extra fields, and re-prompt the LLM on failure.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Post-process the JSON output to filter out unexpected keys before validation.",
      "success_rate": 0.85,
      "how": "Post-process the JSON output to filter out unexpected keys before validation.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Use Pydantic's 'extra' parameter set to 'forbid' to reject extra fields, and re-prompt the LLM on failure.",
    "Post-process the JSON output to filter out unexpected keys before validation."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://platform.openai.com/docs/guides/text-generation/json-mode",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.81,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-11-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}