invalid_response_format llm config_error ai_generated true

openai.BadRequestError: Invalid schema for response_format: 'properties' must be an object

ID: llm/structured-output-schema-mismatch-on-retry

Also available as: JSON · Markdown · 中文
88%Fix Rate
85%Confidence
1Evidence
2024-06-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
openai==1.30.0 active — — —
openai==1.35.0 active — — —
pydantic==2.7.0 active — — —

Root Cause

OpenAI API enforces strict JSON Schema validation for response_format; an empty or malformed 'properties' field (e.g., after schema transformation or caching) triggers this error on retry.

generic

中文

OpenAI API 对 response_format 强制执行严格的 JSON Schema 验证；空的或格式错误的 'properties' 字段（例如在架构转换或缓存后）会在重试时触发此错误。

Official Documentation

https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format

Workarounds

  1. 90% success Validate the schema before sending: ensure 'properties' is a non-empty object with valid JSON Schema types. Example: `if not isinstance(schema.get('properties'), dict) or len(schema['properties']) == 0: raise ValueError('Invalid schema')` 
    Validate the schema before sending: ensure 'properties' is a non-empty object with valid JSON Schema types. Example: `if not isinstance(schema.get('properties'), dict) or len(schema['properties']) == 0: raise ValueError('Invalid schema')`
  2. 95% success Use a schema generation library like Pydantic to create the JSON Schema, then convert to dict with `model_json_schema()`. Example: `from pydantic import BaseModel; class MyModel(BaseModel): name: str; schema = MyModel.model_json_schema()` 
    Use a schema generation library like Pydantic to create the JSON Schema, then convert to dict with `model_json_schema()`. Example: `from pydantic import BaseModel; class MyModel(BaseModel): name: str; schema = MyModel.model_json_schema()`
  3. 85% success If caching schemas, deep-copy the schema dict before modification to avoid mutating the cached version (which may become empty). Example: `import copy; schema = copy.deepcopy(cached_schema)` 
    If caching schemas, deep-copy the schema dict before modification to avoid mutating the cached version (which may become empty). Example: `import copy; schema = copy.deepcopy(cached_schema)`

中文步骤

  1. Validate the schema before sending: ensure 'properties' is a non-empty object with valid JSON Schema types. Example: `if not isinstance(schema.get('properties'), dict) or len(schema['properties']) == 0: raise ValueError('Invalid schema')`
  2. Use a schema generation library like Pydantic to create the JSON Schema, then convert to dict with `model_json_schema()`. Example: `from pydantic import BaseModel; class MyModel(BaseModel): name: str; schema = MyModel.model_json_schema()`
  3. If caching schemas, deep-copy the schema dict before modification to avoid mutating the cached version (which may become empty). Example: `import copy; schema = copy.deepcopy(cached_schema)`

Dead Ends

Common approaches that don't work:

  1. 95% fail

    The schema is fundamentally broken; the API will reject it consistently until the schema is corrected.

  2. 85% fail

    Removing structured output forces the LLM to return free-form text, breaking downstream parsing logic that expects a JSON object.

  3. 90% fail

    The API expects the schema directly under 'response_format', not nested; this causes a different validation error.