Hyrum's Law
debt(d9/e7/b7/t9)
Closest to 'silent in production until users hit it' (d9). The detection_hints explicitly state 'automated: no' and the code_pattern describes implicit dependencies (e.g., undocumented JSON key ordering, accidental format consistency) that produce no warnings, no linter signals, and no compile-time errors. The breakage only surfaces when downstream consumers — potentially unknown to the API author — start failing in production after a change.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix acknowledges that every observable behaviour must be treated as a potential contract, meaning remediation isn't a single patch but a systemic rethink: auditing all observable behaviours, adding API versioning, coordinating with consumers, and potentially maintaining compatibility shims. The common_mistakes (JSON key order, error message parsing, bug workarounds) each require coordinated changes across provider and consumer codebases.
Closest to 'strong gravitational pull' (b7). The applies_to scope covers web and api contexts broadly, and the tags include architecture. Once an API has grown a Hyrum-dependent user base, every future change must be evaluated against all observable behaviours — not just the documented contract. This shapes the entire evolution of the API: every refactor, bug fix, or optimisation carries risk of breaking implicit dependents, imposing a persistent and widening tax on maintainers.
Closest to 'catastrophic trap — the obvious way is always wrong' (t9). The misconception field precisely captures the trap: developers naturally assume 'undocumented = changeable', which is exactly wrong for any sufficiently observed API. The common_mistakes reinforce this — fixing a bug, reordering JSON keys, or changing error strings all seem safe by conventional reasoning but reliably break real consumers. The gap between intuition (only contracts matter) and reality (all stable observations become contracts) is maximum.
Also Known As
TL;DR
Explanation
Hyrum's Law (Hyrum Wright, Google) states that any behaviour your system exhibits — including bugs, performance characteristics, and undocumented side effects — will eventually be relied upon by some user. This has profound implications for API versioning and library maintenance: even changing a bug fix can break consumers. It explains why 'just fix the bug' is often not simple in widely-used APIs. Practically, it means documented contracts are necessary but not sufficient — the full observable behaviour is the real contract.
Common Misconception
Why It Matters
Common Mistakes
- Changing the order of JSON object keys (technically undefined) — some parsers depend on field order.
- Fixing a bug that consumers have worked around — their workaround breaks when the bug is fixed.
- Changing error message strings — some consumers parse error messages rather than error codes.
- Not versioning APIs before changing behaviour — even a 'minor' change breaks Hyrum-dependent consumers.
Code Examples
// Undocumented behaviour that becomes a dependency:
// API returns users sorted by ID (unspecified, implementation detail)
// 10,000 consumers display users assuming ID order
// Developer refactors to sort by name (more logical)
// 10,000 consumers silently display wrong order
// No API version change made — 'order was never documented'// Explicit sort contract prevents Hyrum dependency:
// API docs: 'users returned in undefined order unless ?sort=name|id|created_at'
// Consumers must specify sort explicitly
// Developer can change default sort safely
// Or: version the API before changing default behaviour