A scorer wrapped in functools.lru_cache raises TypeError: unhashable type: 'dict' — why, and how do you fix it?

## What the error is telling you `functools.lru_cache` (and `functools.cache`, which is `lru_cache(maxsize=None)`) works by building a key from the arguments of each call and looking it up in a dict. That is the whole mechanism, and it inherits the dict's requirement: **every argument must be hashable**. Pass a `dict`, `list` or `set` and the first call raises before your function body ever runs: ```python @functools.lru_cache(maxsize=256) def score(features): ... score({"ctr": 0.2, "bid": 1.5}) # TypeError: unhashable type: 'dict' ``` Nothing is wrong with the cache. The error is the mutability rule showing up at an API boundary: if the mapping could be edited after the call, an entry stored under its old contents would be wrong for its new contents, and the cache would confidently serve a stale answer. ## The canonical-key fix Give the cached function a parameter that is already immutable, and do the conversion at the boundary: ```python import functools @functools.cache def _score(features): # features: frozenset of (name, value) return round(sum(v for _, v in features), 3) def score(config: dict) -> float: return _score(frozenset(config.items())) ``` The public function keeps the ergonomic dict signature; the private one takes something the cache can key on. `frozenset(config.items())` is a good choice for a flat mapping because it is order-insensitive: two configs built in different orders produce equal keys and equal hashes, so they share a cache entry. When you want a deterministic, orderable key instead, use `tuple(sorted(config.items()))`. Both forms require the *values* to be hashable too. A config holding a nested list needs that list turned into a tuple first, recursively if the structure nests. At that point the honest question is whether the argument should be a structure at all: an immutable value type — a `collections.namedtuple`, or a `dataclasses.dataclass(frozen=True)` — hashes on its fields, documents what the key means, and stops the recursion problem at the source. ## Canonicalisation is the part people get wrong The failure that actually reaches production is not the `TypeError`, which is loud and immediate. It is a key that *works* but is not canonical. `tuple(config.items())` hashes fine and never raises, so it sails through review, but it encodes insertion order into the key. Two callers assembling the same settings in different orders get two entries. Under a sustained peak of around 1,200 requests per minute, an ad-auction bidder built this way looks healthy in every metric except the one that matters: the hit rate is a fraction of what it should be, the cache churns through evictions, and latency climbs for reasons no single trace explains. The rule to state out loud is: **two inputs your code treats as equivalent must produce one key**. ## Diagnosing it A cached function exposes `cache_info()`, which reports hits, misses, `maxsize` and `currsize`. Two numbers answer the question quickly: a hit count near zero across a warm workload means the key is not canonical, and a `currsize` pinned at `maxsize` with hits still climbing means the cache is simply too small for the working set. `cache_clear()` resets it between measurements. Take these readings before tuning `maxsize`, because sizing a cache whose keys do not collapse correctly just spends more memory on the same duplication. ## When not to reach for the conversion Sometimes the argument is genuinely mutable and genuinely large, and freezing it per call costs more than the cached computation saves — the conversion is O(n) in the size of the mapping, on every call, including the hits. In that case, cache at a different level: key on something small and stable that already identifies the input, such as a version counter or an identifier the caller already has, and keep the structure out of the signature entirely. The other case to be careful about is lifetime. `lru_cache` holds strong references to both arguments and results for as long as the entry lives, so an unbounded `functools.cache` on a function taking large keys is an unbounded memory growth path attached to a function object that lives for the whole process. Bound it with `maxsize` unless the key space is genuinely finite and small.