LangGraph checkpoint turns typed map keys into strings

An agent can save state successfully and still read back a different key type. An open LangGraph issue shows an Enum dictionary key becoming its string value after a checkpoint round trip; the reporter also identifies UUID and date keys as affected. The example counter starts over for the Enum key on each resumed invocation while an integer key continues correctly. This is a reported serialization boundary, not proof that every checkpoint backend behaves identically.

Test the round trip, not only the write

Build a minimal state with one key of each type your workflow uses. Invoke the graph, read the checkpoint, then invoke it again under the same thread ID. Assert both value and key type after each round trip. The LangGraph persistence documentation explains how checkpoints preserve thread state for continuation and recovery. A passing first invocation does not establish safe replay.

Choose a stable state shape

For production state, prefer string keys with an explicit, versioned encoding when identity matters. Convert to typed values at the application boundary and test collisions: a string red must not silently alias an Enum whose value is red. If the state schema already uses typed keys, identify affected checkpoints before changing representation, because historical data may need migration.

Guard operational outcomes

A key lookup miss can cause duplicated actions, lost counters, or a false assumption that prior work never happened. Before making a retry automatic, check how the application records completed side effects outside graph state. Ask for a serialized-state fixture and a resume test that covers the deployed serializer version.

Adovo’s view

Persistence is useful only if identity survives the round trip. A checkpoint that changes what a key means can make the workflow repeat itself. Treat type preservation as data integrity, not a serializer detail.