ValidationError
pydantic.error_wrappers.ValidationError
Stack trace
pydantic.error_wrappers.ValidationError: 1 validation error for WorkflowState
field_name
field required (type=value_error.missing)
File "/usr/local/lib/python3.9/site-packages/langgraph/workflow.py", line 123, in run
state = WorkflowState.parse_obj(raw_state) # <-- triggers ValidationError
Why it happens
LangGraph workflows rely on strict Pydantic schemas to validate the state at each step. If the state dictionary is missing required fields, has incorrect types, or extra unexpected fields, Pydantic raises a ValidationError. This often happens when the workflow logic or state mutations do not align with the declared schema.
Detection
Catch ValidationError exceptions around state parsing or updating calls and log the raw state data to identify missing or malformed fields before the workflow crashes.
Causes & fixes
The workflow state is missing required fields defined in the Pydantic schema.
Ensure all required fields are present in the state dictionary before passing it to the workflow or updating the state.
State fields have incorrect data types that do not match the schema definitions.
Validate and cast state field values to the correct types before updating the workflow state.
Extra unexpected fields are present in the state that the schema does not allow.
Remove or ignore unknown fields from the state dictionary or update the schema to accept them if intentional.
State mutations in workflow steps do not return the updated state conforming to the schema.
Review and fix workflow step implementations to return fully valid state objects matching the schema.
Code: broken vs fixed
from langgraph import Workflow
workflow = Workflow(...)
raw_state = {'some_field': 'value'} # Missing required fields
workflow.run(state=raw_state) # This line triggers ValidationErrorimport os
from langgraph import Workflow
from pydantic import BaseModel
os.environ['LANGGRAPH_API_KEY'] = os.environ.get('LANGGRAPH_API_KEY', 'your_api_key_here') # Use env var for keys
class MyWorkflowState(BaseModel):
some_field: str
required_field: int
workflow = Workflow(...)
valid_state = MyWorkflowState(some_field='value', required_field=1).dict()
workflow.run(state=valid_state) # Fixed: state matches schema
print('Workflow ran successfully with valid state')Workaround
Wrap the workflow run call in try/except ValidationError, log the invalid state, and manually fix or fill missing fields before retrying.
Prevention
Define and enforce strict Pydantic schemas for workflow states and use automated validation and type checking during state mutations to prevent schema mismatches.