Checkpointer silently converts `StrEnum` fields into `str` when serializing/deserializing

[strentom]

Checked other resources

• This is a bug, not a usage question. For questions, please use the LangChain Forum (https://forum.langchain.com/).
• I added a clear and detailed title that summarizes the issue.
• I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
• I included a self-contained, minimal example that demonstrates the issue INCLUDING all the relevant imports. The code run AS IS to reproduce the issue.

Example Code

from enum import Enum, StrEnum
from typing import TypedDict

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, StateGraph


class RegularEnum(Enum):
    PENDING = "pending"
    COMPLETED = "completed"


class StringEnum(StrEnum):
    PENDING = "pending"
    COMPLETED = "completed"


class GraphState(TypedDict):
    regular: RegularEnum
    string: StringEnum


def process_node(state: GraphState) -> GraphState:
    return {"regular": RegularEnum.COMPLETED, "string": StringEnum.COMPLETED}


# Build and run graph
workflow = StateGraph(GraphState)
workflow.add_node("process", process_node)
workflow.set_entry_point("process")
workflow.add_edge("process", END)

checkpointer = MemorySaver()
app = workflow.compile(checkpointer=checkpointer)

print("=== Running graph with both enum types ===")
result = app.invoke(
    {"regular": RegularEnum.PENDING, "string": StringEnum.PENDING},
    config={"configurable": {"thread_id": "test"}}
)
print(f"Result after invoke: {result}\n")

print("=== Retrieving state from checkpointer ===")
state = app.get_state(config={"configurable": {"thread_id": "test"}})
print(f"Regular Enum - Type: {type(state.values['regular'])}, Value: {state.values['regular']}")
print(f"String Enum  - Type: {type(state.values['string'])}, Value: {state.values['string']}")

Error Message and Stack Trace (if applicable)

Description

• I'm trying to store a custom class that inherits StrEnum in graph's State. My class inherits StrEnum and has custom methods.
• Langgraph/checkpointer silently converts my class (inheriting StrEnum) into str. This doesn't happen when class extends just Enum.
• There should either be a warning or an exception, not a silent type conversion.

System Info

System Information
------------------
> OS:  Darwin
> OS Version:  Darwin Kernel Version 24.6.0: Wed Oct 15 21:12:08 PDT 2025; root:xnu-11417.140.69.703.14~1/RELEASE_ARM64_T6020
> Python Version:  3.12.11 (main, Oct  9 2025, 10:09:01) [Clang 16.0.0 (clang-1600.0.26.6)]

Package Information
-------------------
> langchain_core: 0.3.78
> langchain: 0.3.27
> langchain_community: 0.4.1
> langsmith: 0.4.33
> langchain_classic: 1.0.0
> langchain_google_genai: 4.0.0
> langchain_google_vertexai: 2.1.2
> langchain_model_profiles: 0.0.5
> langchain_openai: 0.3.35
> langchain_text_splitters: 0.3.11
> langgraph_api: 0.4.38
> langgraph_cli: 0.4.3
> langgraph_license: Installed. No version info available.
> langgraph_runtime: Installed. No version info available.
> langgraph_runtime_inmem: 0.14.1
> langgraph_sdk: 0.2.9
> langgraph_supervisor: 0.0.28

Optional packages not installed
-------------------------------
> langserve

Other Dependencies
------------------
> aiohttp<4.0.0,>=3.8.3: Installed. No version info available.
> anthropic<1,>=0.35;: Installed. No version info available.
> async-timeout<5.0.0,>=4.0.0;: Installed. No version info available.
> blockbuster<2.0.0,>=1.5.24: Installed. No version info available.
> bottleneck<2,>=1.4: Installed. No version info available.
> click>=8.1.7: Installed. No version info available.
> cloudpickle>=3.0.0: Installed. No version info available.
> cryptography<45.0,>=42.0.0: Installed. No version info available.
> dataclasses-json<0.7.0,>=0.6.7: Installed. No version info available.
> filetype<2.0.0,>=1.2.0: Installed. No version info available.
> google-cloud-aiplatform>=1.97.0: Installed. No version info available.
> google-cloud-storage<3,>=2.18: Installed. No version info available.
> google-genai<2.0.0,>=1.53.0: Installed. No version info available.
> grpcio-tools<2.0.0,>=1.75.0: Installed. No version info available.
> grpcio<2.0.0,>=1.75.0: Installed. No version info available.
> httpx-sse<1,>=0.4: Installed. No version info available.
> httpx-sse<1.0.0,>=0.4.0: Installed. No version info available.
> httpx<1,>=0.23.0: Installed. No version info available.
> httpx<1,>=0.28: Installed. No version info available.
> httpx>=0.25.0: Installed. No version info available.
> httpx>=0.25.2: Installed. No version info available.
> jsonpatch<2.0.0,>=1.33.0: Installed. No version info available.
> jsonschema-rs<0.30,>=0.20.0: Installed. No version info available.
> langchain-anthropic;: Installed. No version info available.
> langchain-aws;: Installed. No version info available.
> langchain-azure-ai;: Installed. No version info available.
> langchain-classic<2.0.0,>=1.0.0: Installed. No version info available.
> langchain-cohere;: Installed. No version info available.
> langchain-community;: Installed. No version info available.
> langchain-core<1.0.0,>=0.3.72: Installed. No version info available.
> langchain-core<1.0.0,>=0.3.78: Installed. No version info available.
> langchain-core<2.0.0,>=0.3.75: Installed. No version info available.
> langchain-core<2.0.0,>=1.0.0: Installed. No version info available.
> langchain-core<2.0.0,>=1.0.1: Installed. No version info available.
> langchain-core<2.0.0,>=1.1.2: Installed. No version info available.
> langchain-core>=0.3.40: Installed. No version info available.
> langchain-core>=0.3.64: Installed. No version info available.
> langchain-core>=0.3.76: Installed. No version info available.
> langchain-deepseek;: Installed. No version info available.
> langchain-fireworks;: Installed. No version info available.
> langchain-google-genai;: Installed. No version info available.
> langchain-google-vertexai;: Installed. No version info available.
> langchain-groq;: Installed. No version info available.
> langchain-huggingface;: Installed. No version info available.
> langchain-mistralai;: Installed. No version info available.
> langchain-mistralai<1,>=0.2.0;: Installed. No version info available.
> langchain-ollama;: Installed. No version info available.
> langchain-openai;: Installed. No version info available.
> langchain-perplexity;: Installed. No version info available.
> langchain-text-splitters<1.0.0,>=0.3.9: Installed. No version info available.
> langchain-text-splitters<2.0.0,>=1.0.0: Installed. No version info available.
> langchain-together;: Installed. No version info available.
> langchain-xai;: Installed. No version info available.
> langgraph-api<0.5.0,>=0.3;: Installed. No version info available.
> langgraph-checkpoint>=2.0.23: Installed. No version info available.
> langgraph-checkpoint>=2.0.25: Installed. No version info available.
> langgraph-runtime-inmem<0.15.0,>=0.14.0: Installed. No version info available.
> langgraph-runtime-inmem>=0.7;: Installed. No version info available.
> langgraph-sdk>=0.1.0;: Installed. No version info available.
> langgraph-sdk>=0.2.0: Installed. No version info available.
> langgraph>=0.2: Installed. No version info available.
> langgraph>=0.4.0: Installed. No version info available.
> langgraph>=0.4.6: Installed. No version info available.
> langsmith-pyo3>=0.1.0rc2;: Installed. No version info available.
> langsmith<1.0.0,>=0.1.125: Installed. No version info available.
> langsmith<1.0.0,>=0.1.17: Installed. No version info available.
> langsmith<1.0.0,>=0.3.45: Installed. No version info available.
> langsmith>=0.1.17: Installed. No version info available.
> langsmith>=0.3.45: Installed. No version info available.
> numexpr<3,>=2.8.6: Installed. No version info available.
> numpy>=1.26.2;: Installed. No version info available.
> numpy>=2.1.0;: Installed. No version info available.
> openai-agents>=0.0.3;: Installed. No version info available.
> openai<3.0.0,>=1.104.2: Installed. No version info available.
> opentelemetry-api>=1.30.0;: Installed. No version info available.
> opentelemetry-api>=1.37.0: Installed. No version info available.
> opentelemetry-exporter-otlp-proto-http>=1.30.0;: Installed. No version info available.
> opentelemetry-exporter-otlp-proto-http>=1.37.0: Installed. No version info available.
> opentelemetry-sdk>=1.30.0;: Installed. No version info available.
> opentelemetry-sdk>=1.37.0: Installed. No version info available.
> orjson>=3.10.1: Installed. No version info available.
> orjson>=3.9.14;: Installed. No version info available.
> orjson>=3.9.7: Installed. No version info available.
> packaging<26.0.0,>=23.2.0: Installed. No version info available.
> packaging>=23.2: Installed. No version info available.
> protobuf<7.0.0,>=6.32.1: Installed. No version info available.
> pyarrow<22,>=19.0.1: Installed. No version info available.
> pydantic-settings<3.0.0,>=2.10.1: Installed. No version info available.
> pydantic<3,>=1: Installed. No version info available.
> pydantic<3,>=2.9: Installed. No version info available.
> pydantic<3.0.0,>=2.0.0: Installed. No version info available.
> pydantic<3.0.0,>=2.7.4: Installed. No version info available.
> pyjwt>=2.9.0: Installed. No version info available.
> pytest>=7.0.0;: Installed. No version info available.
> python-dotenv>=0.8.0;: Installed. No version info available.
> PyYAML<7.0.0,>=5.3.0: Installed. No version info available.
> pyyaml<7.0.0,>=5.3.0: Installed. No version info available.
> PyYAML>=5.3: Installed. No version info available.
> requests-toolbelt>=1.0.0: Installed. No version info available.
> requests<3,>=2: Installed. No version info available.
> requests<3.0.0,>=2.0.0: Installed. No version info available.
> requests<3.0.0,>=2.32.5: Installed. No version info available.
> requests>=2.0.0: Installed. No version info available.
> rich>=13.9.4;: Installed. No version info available.
> SQLAlchemy<3,>=1.4: Installed. No version info available.
> SQLAlchemy<3.0.0,>=1.4.0: Installed. No version info available.
> sqlalchemy<3.0.0,>=1.4.0: Installed. No version info available.
> sse-starlette<2.2.0,>=2.1.0: Installed. No version info available.
> sse-starlette>=2: Installed. No version info available.
> starlette>=0.37: Installed. No version info available.
> starlette>=0.38.6: Installed. No version info available.
> structlog<26,>=24.1.0: Installed. No version info available.
> structlog>23: Installed. No version info available.
> tenacity!=8.4.0,<10.0.0,>=8.1.0: Installed. No version info available.
> tenacity>=8.0.0: Installed. No version info available.
> tiktoken<1.0.0,>=0.7.0: Installed. No version info available.
> tomli<3.0.0,>=2.0.0;: Installed. No version info available.
> truststore>=0.1: Installed. No version info available.
> typing-extensions<5.0.0,>=4.7.0: Installed. No version info available.
> uvicorn>=0.26.0: Installed. No version info available.
> validators<1,>=0.22: Installed. No version info available.
> vcrpy>=7.0.0;: Installed. No version info available.
> watchfiles>=0.13: Installed. No version info available.
> zstandard>=0.23.0: Installed. No version info available.

[Rakshit-gen]

assign this to me

[strentom]

Thank you @Rakshit-gen

Note: please check other typed enums (IntEnum,..?) don’t suffer from the same issue. Thanks again.

[Rakshit-gen]

Hey @strentom All enum types work correctly. The issue was specific to StrEnum because:
StrEnum is both an Enum and a str
ormsgpack has native string handling that could serialize it as a string before the Enum check
IntEnum, Flag, and IntFlag don't have this issue because ormsgpack doesn't have native handling for their base types that would bypass the Enum check.

[strentom]

And what about class X(Enum, str) for older python?

[Rakshit-gen]

@strentom I have verified that other typed enums including IntEnum, IntFlag, and backported string enums (defined as class X(str, Enum)) work correctly and are preserved during serialization

[Rakshit-gen]

@strentom any updates on merging the PR?

[strentom]

@Rakshit-gen I didn't check the PR but from your responses here it seems good. Thank you very much.

[Rakshit-gen]

@strentom hey thanks, can we merge the pr then?