RefusalFieldError
openai.RefusalFieldError
Stack trace
openai.RefusalFieldError: The model refused to provide a value for a required field in the structured output.
File "app.py", line 42, in generate_structured_output
response = client.chat.completions.create(...)
File "/usr/local/lib/python3.10/site-packages/openai/api_resources/chat_completion.py", line 75, in create
raise RefusalFieldError("Refusal field triggered in structured output") Why it happens
OpenAI's structured output feature enforces that the model must fill all required fields. If the model refuses to provide a value: often due to content policy restrictions or ambiguous prompt instructions: the API raises a refusal field error. This prevents incomplete or policy-violating outputs from being returned.
Detection
Monitor API responses for RefusalFieldError exceptions and log the raw LLM output and prompt context to identify which field triggered refusal before retrying or adjusting the prompt.
Causes & fixes
The prompt or schema requests sensitive or disallowed content causing the model to refuse filling the field.
Review and sanitize prompt instructions and schema fields to avoid requesting content that violates OpenAI's content policies.
The required field is ambiguous or unclear, leading the model to refuse to provide a value.
Clarify the prompt instructions and provide explicit examples to guide the model in filling the required fields.
Using a base model without instruction tuning that does not reliably follow refusal field requirements.
Switch to an instruction-tuned model like gpt-4o-mini or claude-3-5-haiku-20241022 that respects refusal field enforcement.
Code: broken vs fixed
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Fill all fields exactly."}],
response_format={"type": "json_schema", "json_schema": {"type": "object", "properties": {"refusal_field": {"type": "string"}}, "required": ["refusal_field"]}}
)
print(response.choices[0].message.content) # This line triggers RefusalFieldErrorfrom openai import OpenAI, RefusalFieldError
import os
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
try:
response = client.chat.completions.create(
model="gpt-4o-mini", # Switched to instruction-tuned model
messages=[{"role": "user", "content": "Please fill all fields with valid content."}],
response_format={"type": "json_schema", "json_schema": {"type": "object", "properties": {"refusal_field": {"type": "string"}}, "required": ["refusal_field"]}}
)
print(response.choices[0].message.content)
except RefusalFieldError as e:
print(f"Refusal field error caught: {e}") # Handle refusal gracefullyWorkaround
Catch RefusalFieldError exceptions and fallback to a simpler prompt or partial parsing, or extract partial data from the raw LLM output ignoring refusal fields temporarily.
Prevention
Design prompts and schemas that avoid requesting disallowed content, use instruction-tuned models, and leverage OpenAI's structured output enforcement to catch refusals early and handle them gracefully.