Mutable Default Argument Bugs

Default argument values are evaluated once at function definition time. Mutable defaults (list, dict, set) become shared state across calls, producing cross-request contamination and "sometimes wrong" test failures.

Recipe

Quick-reference recipe card - copy-paste ready.

# BUG
def append_item(item, bucket=[]):
    bucket.append(item)
    return bucket
 
# FIX
def append_item(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

When to reach for this:

• API handlers accumulate items across unrelated requests
• Unit tests pass alone but fail when run as a suite
• Logging or metrics collectors grow forever across calls
• @dataclass fields use mutable defaults incorrectly (related pattern)

Working Example

# broken_session_store.py
from dataclasses import dataclass, field
 
def broken_add_token(user_id: str, token: str, store: dict[str, list[str]] = {}) -> dict[str, list[str]]:
    store.setdefault(user_id, []).append(token)
    return store
 
# symptoms
broken_add_token("u1", "a")
broken_add_token("u2", "b")
print(broken_add_token("u1", "c"))  # u1 now has tokens from earlier polluted store
 
# fixed_session_store.py
def add_token(
    user_id: str,
    token: str,
    store: dict[str, list[str]] | None = None,
) -> dict[str, list[str]]:
    if store is None:
        store = {}
    store.setdefault(user_id, []).append(token)
    return store
 
@dataclass
class SessionStore:
    _data: dict[str, list[str]] = field(default_factory=dict)
 
    def add(self, user_id: str, token: str) -> None:
        self._data.setdefault(user_id, []).append(token)
 
# tests/test_session_store.py
from fixed_session_store import SessionStore, add_token
 
def test_add_token_isolated_calls() -> None:
    assert add_token("u1", "x") == {"u1": ["x"]}
    assert add_token("u2", "y") == {"u2": ["y"]}
 
def test_session_store_dataclass() -> None:
    a = SessionStore()
    b = SessionStore()
    a.add("u1", "t1")
    assert b._data == {}

What this demonstrates:

• Default {} is one shared dict for all calls to broken_add_token
• None sentinel creates a fresh dict per call when omitted
• @dataclass uses field(default_factory=dict) for the same reason
• Tests prove isolation between instances and calls

Deep Dive

How It Works

• Function defaults bind at def execution, not per call
• The same list/dict object is reused when the caller omits the argument
• Dataclass field defaults follow the same rule without default_factory
• Immutable defaults (None, 0, "", tuples) are safe

Safe vs Unsafe Defaults

Python Notes

# typing makes intent clear
def process(items: list[int] | None = None) -> list[int]:
    working = list(items) if items is not None else []
    working.append(1)
    return working

Gotchas

• Only some requests affected - heisenbug under concurrency reuses worker process memory. Fix: remove mutable defaults; restart masks but does not fix.
• Dataclass = {} field - same bug in classes. Fix: field(default_factory=dict).
• Copying the default manually wrong - bucket = bucket or [] treats empty list as missing. Fix: if bucket is None.
• Mutating caller's list when provided - surprising side effect when default is not used. Fix: working = list(bucket) if you must not alias input.
• Caching with @lru_cache on methods with hidden mutable state - cache + mutation compounds confusion. Fix: pure functions or explicit instance state.
• FastAPI Depends with mutable default - rare but possible in custom dependency signatures. Fix: use None sentinel pattern.

Alternatives

FAQs

Related

• Domain Modeling - dataclass default_factory
• Memory Leak Scenarios - unbounded growth from shared caches
• Debugging Refactor Snippets - before/after fixes
• Debugging Tools - inspect with pdb
• Architecture Best Practices - avoid shared mutable state

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.