A LangGraph cached task fails before it can run on mixed map keys

A cached agent task can fail before its first line executes. A current LangGraph issue reproduces a TypeError when a keyword argument contains a mapping whose keys are hashable but not orderable, such as Enum members or a mix of strings and integers. The default cache-key builder sorts those keys. The result is a crash at cache-key generation, not a failure inside the task body.

Confirm where the failure occurs

Record the task’s input shape, call style, cache policy, and package version. In the issue reproduction, @task(cache_policy=CachePolicy()) receives an Enum-keyed dictionary as a keyword argument; the task counter stays at zero. That distinction matters because retrying the task body or changing its prompt cannot help. LangGraph’s graph documentation says cache policies use a key function, and a custom one can be supplied.

Choose an explicit input contract

If your application controls the input, normalize keys before calling the cached task. Preserve type in the canonical representation: 1 and "1" must not collapse to the same string. Add tests that permute mapping order and cover Enum, integer, string, and None keys. If input normalization would change business semantics, supply a tested custom key_func for that task instead. It must produce the same key for semantically identical inputs and different keys for meaningfully different ones.

Verify the cache as well as execution

Run the same logical input twice and assert the task executes once. Change one meaningful field and assert it executes again. Keep a cache-disabled fallback if the workflow is urgent and the key contract is not yet trustworthy. Track the upstream issue before removing the mitigation; the reporter describes a proposed fix, but a proposal is not a released guarantee.

Adovo’s view

Caching is a correctness decision disguised as a speed decision. The cache key defines which two requests the system considers the same. Own that definition at the application boundary, or an agent can be fast for the wrong reason and fail before it works.