{
  "id": "llm/langchain-output-parser-enum",
  "signature": "OutputParserException: Parsing LLM output produced by 'StructuredOutputParser' failed — value 'large' not in enum ['small', 'medium']",
  "signature_zh": "OutputParserException：由'StructuredOutputParser'生成的 LLM 输出解析失败——值'large'不在枚举['small', 'medium']中",
  "regex": "OutputParserException.*Parsing LLM output.*enum.*not in",
  "domain": "llm",
  "category": "data_error",
  "subcategory": null,
  "root_cause": "LLM generated a value outside the specified enum constraints when using LangChain's structured output parsers with Pydantic models, often due to insufficient prompting or model hallucination.",
  "root_cause_type": "generic",
  "root_cause_zh": "LLM 在使用 LangChain 的结构化输出解析器和 Pydantic 模型时生成了指定枚举约束之外的值，通常是由于提示不足或模型幻觉。",
  "versions": [
    {
      "version": "langchain>=0.1.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "langchain-core>=0.1.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"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "This defeats the purpose of constrained output; the LLM may still generate unexpected values outside the expanded set",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Even with temperature=0, LLMs can produce non-deterministic outputs due to floating-point rounding or model updates",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Silent fallback masks errors and may produce incorrect downstream results, leading to hard-to-debug issues",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Improve the prompt to explicitly list allowed enum values and instruct the model to only output those exact values: 'The size must be exactly one of: small, medium. Do not output any other value.'",
      "success_rate": 0.85,
      "how": "Improve the prompt to explicitly list allowed enum values and instruct the model to only output those exact values: 'The size must be exactly one of: small, medium. Do not output any other value.'",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use LangChain's with_structured_output method on chat models that support JSON mode, which enforces schema constraints at the API level rather than relying on parsing.",
      "success_rate": 0.9,
      "how": "Use LangChain's with_structured_output method on chat models that support JSON mode, which enforces schema constraints at the API level rather than relying on parsing.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Implement a post-processing fallback that maps out-of-enum values to the closest valid enum member using a similarity heuristic or manual mapping.",
      "success_rate": 0.75,
      "how": "Implement a post-processing fallback that maps out-of-enum values to the closest valid enum member using a similarity heuristic or manual mapping.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "改进提示，显式列出允许的枚举值，并指示模型仅输出这些确切值：'大小必须恰好是以下之一：small, medium。不要输出任何其他值。'",
    "在支持 JSON 模式的聊天模型上使用 LangChain 的 with_structured_output 方法，该方法在 API 级别强制模式约束，而不是依赖解析。",
    "实现一个后处理回退，使用相似度启发式或手动映射将超出枚举的值映射到最接近的有效枚举成员。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://python.langchain.com/docs/modules/model_io/output_parsers/structured",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.8,
  "resolvable": "partial",
  "first_seen": "2024-05-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}