Why does @dataclass raise ValueError for `tags: list = []`, and what is the fix?

## The bug the check exists to prevent A class body executes once. Whatever you assign there is created once, and the generated `__init__` would hand that single object to every instance: ```python # what the decorator would have to generate def __init__(self, name, tags=[]): # the [] is built once self.tags = tags ``` Every row you construct would then share one list. Consider importing a payroll CSV for an 11-person team, where each row is a small record with a `deductions` list: the first employee's pension entry appends into the shared list, the second row appends into the *same* list, and by the end of the import every one of the 11 records reports all 11 deductions. It is the classic duplicated side effect — nothing raises, the numbers are simply wrong, and it usually surfaces in production as "the totals are too big" long after the import ran. This is exactly the mutable-default-argument trap, moved into a class body. In a plain function Python lets you do it; in a dataclass the decorator has enough information to notice, so it refuses. ## What actually happens ```pycon >>> from dataclasses import dataclass >>> @dataclass ... class Row: ... tags: list = [] ... ValueError: mutable default <class 'list'> for field tags is not allowed: use default_factory ``` Note *when* it happens: at class-creation time, while the decorator runs — not on first instantiation. The module simply fails to import, which is the friendliest possible failure mode. ## The fix: default_factory ```python from dataclasses import dataclass, field @dataclass class PayrollRow: name: str deductions: list[str] = field(default_factory=list) ``` `dataclasses.field()` is not a value — it is a specification object the decorator consumes and replaces. `default_factory` takes a **zero-argument callable**, and the generated `__init__` calls it once per construction when the argument is omitted. Pass the callable itself: `default_factory=list`, not `default_factory=list()`. The latter stores an empty list as the "factory" and blows up at construction with `TypeError: 'list' object is not callable`. Anything zero-argument works: `dict`, `set`, `functools.partial(...)`, a `lambda: {"attempts": 0}`, `uuid.uuid4`, `datetime.datetime.now`. That last pair is the other half of the idiom — a timestamp or an id default must be computed per instance, not frozen at import time, and `field(default_factory=...)` is how you say so. Note also that `default` and `default_factory` are mutually exclusive; supplying both is an error. ## Why a plain function is allowed to do this A regular function may declare `def add(item, items=[])` and Python will not stop it: the default is evaluated once at `def` time and stored on the function object, and the accumulating-list bug is on the author. The dataclass field default is the *same mechanism* — the class-body value becomes the parameter default of the generated `__init__` — but here the decorator sits between you and the signature and has a chance to inspect the value first, so it does. That asymmetry is worth stating in an interview: dataclasses are not applying a different rule about defaults, they are applying the same rule with a guard in front of it. ## What the check actually tests — and its limits Up to Python 3.10 the decorator tested whether the default was an instance of `list`, `dict` or `set`. **Python 3.11 changed the rule to hashability**: a default is rejected when it is unhashable. That is a better proxy for "mutable", and it means a custom class that sets `__hash__ = None` is rejected too: ```pycon >>> class Bag: ... __hash__ = None ... >>> @dataclass ... class Holder: ... b: Bag = Bag() ... ValueError: mutable default <class '__main__.Bag'> for field b is not allowed: use default_factory ``` The important limit is the converse: a **mutable but hashable** object sails straight through. A default that is an instance of an ordinary class — mutable attributes, inherited identity hash — is accepted and then shared by every instance, reproducing the original bug with no error at all. Treat the check as a guard against the three obvious cases, not as a guarantee. The habit that actually protects you is: if the default is not an immutable scalar, `str`, `bytes`, `None`, or a tuple of those, use `default_factory`. ## Related traps worth naming A tuple default is fine and often the cleanest fix for a small constant sequence, because tuples are immutable and hashable. An empty *frozen* set constant is likewise fine. And a factory that closes over shared state — `field(default_factory=lambda: CACHE)` — rebuilds nothing and hands out the same object again; the callable must *create*, not *fetch*. ## Version notes `dataclasses` shipped in Python 3.7 with the list/dict/set check. Python 3.11 generalised it to "unhashable defaults are rejected", which is the behaviour on 3.14. The error message and the `default_factory` remedy have been stable throughout.