Why Do Pydantic date Fields Fail in LangGraph State?

Problem

When using Pydantic models for LangGraph state, date fields are serialized as JSON arrays [year, month, day] instead of ISO format strings. This causes validation errors when LangGraph deserializes the state back into a Pydantic model.

Error: Pydantic complains that a date was expected but a list was provided.

Root Cause

LangGraph's JsonPlusSerializer serializes date objects as tuples [year, month, day] to match the date constructor signature. Pydantic expects a date object or ISO string when deserializing—not a list.

In contrast, datetime objects serialize as ISO strings (e.g., 2025-12-11T00:00:00), which Pydantic handles correctly.

Solutions

Option 1: Use datetime Instead of date (Recommended)

from pydantic import BaseModel
from datetime import datetime

class MyState(BaseModel):
    due_date: datetime  # Serializes as "2025-12-11T00:00:00"

# Extract date portion when needed:
date_only = state.due_date.date()

Option 2: Use a String Field

from pydantic import BaseModel

class MyState(BaseModel):
    due_date: str  # Store as "2025-12-11"

Option 3: Custom Serializer

from pydantic import BaseModel, field_serializer, field_validator
from datetime import date

class MyState(BaseModel):
    due_date: date
    
    @field_serializer('due_date')
    def serialize_date(self, value: date) -> str:
        return value.isoformat()
    
    @field_validator('due_date', mode='before')
    @classmethod
    def parse_date(cls, v):
        if isinstance(v, str):
            return date.fromisoformat(v)
        if isinstance(v, list):
            return date(*v)  # Handle existing checkpoints
        return v

Quick Reference

Related Resources

1. Pydantic Serialization - Field Serializers

2. Pydantic Standard Library Types - Datetimes

3. LangGraph - Use Pydantic Models for Graph State

4. LangGraph Persistence - Serializer