How to handle validation errors in Instructor
Quick answer
In
Instructor, validation errors occur when the AI response does not conform to the expected response_model schema. Handle these by catching pydantic.ValidationError exceptions around your API call to gracefully manage and debug invalid outputs. ERROR TYPE
api_error ⚡ QUICK FIX
Wrap your
client.chat.completions.create call in a try-except block catching pydantic.ValidationError to handle validation errors explicitly.Why this happens
Instructor uses pydantic models to parse and validate AI responses automatically. If the AI returns data that does not match the expected schema (e.g., missing required fields or wrong types), pydantic.ValidationError is raised. This typically happens when the prompt or model output format is ambiguous or the model generates unexpected content.
Example of triggering code:
import instructor
from openai import OpenAI
from pydantic import BaseModel
import os
client = instructor.from_openai(OpenAI(api_key=os.environ["OPENAI_API_KEY"]))
class User(BaseModel):
name: str
age: int
# AI response missing 'age' field or with wrong type triggers validation error
user = client.chat.completions.create(
model="gpt-4o-mini",
response_model=User,
messages=[{"role": "user", "content": "Extract: John is 30 years old"}]
)
print(user.name, user.age) output
pydantic.ValidationError: 1 validation error for User age field required (type=value_error.missing)
The fix
Catch pydantic.ValidationError exceptions to handle invalid AI responses gracefully. This allows you to log errors, retry, or fallback without crashing your app.
Corrected code example:
import instructor
from openai import OpenAI
from pydantic import BaseModel, ValidationError
import os
client = instructor.from_openai(OpenAI(api_key=os.environ["OPENAI_API_KEY"]))
class User(BaseModel):
name: str
age: int
try:
user = client.chat.completions.create(
model="gpt-4o-mini",
response_model=User,
messages=[{"role": "user", "content": "Extract: John is 30 years old"}]
)
print(user.name, user.age)
except ValidationError as e:
print("Validation error:", e)
# Handle error: log, retry, or fallback output
Validation error: 1 validation error for User age field required (type=value_error.missing)
Preventing it in production
To avoid runtime crashes from validation errors in production:
- Use try-except blocks around
client.chat.completions.createcalls withresponse_model. - Validate and sanitize prompts to encourage consistent AI output formats.
- Implement retries with exponential backoff if validation fails due to transient model output issues.
- Log validation errors with context for debugging and improving prompt design.
- Consider fallback logic to default values or simpler parsing if validation repeatedly fails.
Key Takeaways
- Always catch
pydantic.ValidationErrorwhen usingresponse_modelin Instructor to handle invalid AI outputs. - Validate prompts and design clear instructions to reduce unexpected AI response formats.
- Implement retries and logging to improve robustness and diagnose validation issues in production.