Heisenbug

Name the software defect whose failure vanishes under observation because attaching a debugger, adding a print, or disabling optimization perturbs the timing window or interleaving it rides on — so disappearance-under-observation is the diagnostic tell, not evidence the bug is gone.

Version

v5 · 2026-09-28 · History

Domain-specific #

499

Domain group

Applied Sciences & Engineering

Origin domain

Computer Science & Software Engineering

Subdomain

Debugging Concurrency → Computer Science & Software Engineering

Core Idea

A heisenbug is a software defect whose act of observation perturbs the conditions under which it manifests, so that attaching a debugger, adding print statements, or disabling optimization makes the failure disappear, returning only when the apparatus is removed. The bug is real and repeatable in principle; observation changes the runtime dynamics — timing windows, memory barriers, thread interleaving — the failure depends on, typically for races or uninitialized-memory uses, so it resolves the triggering condition rather than the bug.

How would you explain it like I'm…

The Shy Bug

Imagine a toy that only breaks when nobody is watching. When you sit down to watch it closely, you make it go a tiny bit slower, and then it works fine. The problem is real; your watching just changes the timing it needs to break.

The Bug That Hides When Watched

A heisenbug is a real bug in a program that disappears when a programmer tries to examine it. Tools for watching a program, like a debugger or extra print messages, slow it down or change it a tiny bit. Many bugs only happen when things occur in a very exact order or timing, so that small change stops the bug from appearing. Once the tools are removed, the bug comes back. The name jokes about a physics idea where measuring something changes it.

Observation-Sensitive Software Bug

A heisenbug is a real, repeatable defect that seems to vanish whenever you observe it. Attaching a debugger, adding print statements, or turning off compiler optimizations changes the program's timing, memory state or code layout. Most heisenbugs come from race conditions, where two threads collide only in a narrow timing window, or from reading uninitialized memory. The observation removes the trigger, not the bug. This is different from a bohrbug, which shows up reliably every time. The name borrows from Heisenberg's uncertainty principle, but the cause here is ordinary overhead, not quantum physics.

 

A heisenbug is a genuine, in-principle repeatable defect whose manifestation depends on a timing-sensitive or nondeterministic execution profile that observation perturbs. Debuggers (via ptrace), logging calls (which can imply memory barriers), instrumentation, or builds with optimization disabled change thread interleavings, timing windows, code layout and memory state. Typical roots are race conditions and reads of uninitialized memory. Observation thus removes the triggering condition, not the bug, and the failure returns when the instrumentation is removed. Consequently, single-trace interactive debugging is structurally inadequate. Effective approaches use low-perturbation instruments: structured logging at production speed, sampling profilers or eBPF, deterministic record-and-replay such as rr, or formal methods like TLA+ and model checking that reason over all executions. The name, from fault-tolerance folklore associated with Jim Gray, borrows from the uncertainty principle only as a metaphor; it sits alongside bohrbugs, mandelbugs and Schrödinbugs.

Scope of Application

The heisenbug lives across the debugging subfields of software and computing, in every runtime where observation carries a load-bearing cost.

• Concurrent programming — the canonical home: a race where adding a printf inserts a memory barrier and resolves it during testing.
• Distributed systems — failures visible only under production latency that vanish when traced or sampled.
• Embedded systems — interrupt-timing bugs that disappear under in-circuit debugging because the JTAG halt changes timing.
• Compiler / runtime engineering — optimization-level undefined behavior that recedes when instrumentation alters code generation.

Clarity

Calling a defect a heisenbug reclassifies a supernatural-seeming failure as structurally ordinary and indicts the debugging method, not the code. It denies the assumption that the instrument is a transparent window: the instrument has a runtime cost that is itself load-bearing for whether the failure fires. So "it works under the debugger" becomes the diagnostic signature, and the sharper question is which load-bearing condition the instrument perturbs.

Manages Complexity

The root causes producing an observation-sensitive failure are a sprawl — data races, uninitialized memory, interrupt-timing windows, optimization-dependent undefined behavior. The heisenbug label compresses that catalogue into one behavioral signature, so the engineer triages from the signature alone. The hundred root causes fold into one parameter — does observation cost close the triggering window? — and the signature carries a fixed branch that rules out halt-and-inspect debugging and routes to a perturbation-minimizing playbook.

Abstract Reasoning

The heisenbug treats the gap between observation profile and production profile as first-class, inverting normal debugging logic. Its diagnostic runs from disappearance-under-observation to a structural verdict, its boundary-drawing rules out single-trace debugging by structure, its interventionist move runs two opposite directions (minimize perturbation to observe, widen the window to provoke), and its classificatory triage places the defect in the bohrbug/heisenbug/mandelbug/Schrödinbug partition to select the playbook.

Knowledge Transfer

Within software the concept transfers as mechanism across every runtime where observation carries a load-bearing cost — the diagnostic, profile-gap object, negative inference, two-direction intervention, and four-way triage carrying intact across concurrency, distributed, embedded, and compiler engineering. Beyond software the mechanism is the prime Observer Effect (kin to Measurement and Disturbance and reproducibility), of which a heisenbug is the software-runtime instance; the software-shaped vocabulary stays home, and the Heisenberg-principle resemblance is shared-shape, not shared-mechanism.

Relationships to Other Abstractions

Current abstraction Heisenbug Domain-specific

Parents (2) — outgoing typed relations

• Heisenbug is a kind of Mandelbug Domain-specific

  A Heisenbug is the observation-perturbed subtype of Mandelbug, distinguished by the fact that the debugging apparatus changes the rare runtime state or timing conjunction that activates the defect.

• Heisenbug is a kind of Observer Effect Prime

  A heisenbug is an observer effect specialized to software faults whose triggering timing or state is perturbed by debugging instrumentation.

Hierarchy paths (7) — routes to 5 parentless roots

• Heisenbug → is a kind of Mandelbug → is a decomposition of Conjunctive Path Activation → presupposes, typical Causality → is a kind of Dependency

Show alternative paths (6)

Neighborhood in Abstraction Space

Heisenbug sits in a sparse region of the domain-specific corpus (74^th percentile for distinctiveness): few abstractions share its structure, so a faithful description tends to retrieve it precisely.

Family — Program Execution & Runtime Concepts (34 abstractions)

Nearest neighbors

• Mandelbug — 0.88
• Error-Message Opacity — 0.83
• Runahead Execution — 0.83
• Requirements Churn — 0.83
• Failure Analysis — 0.82

Computed from structural-signature embeddings · 2026-10-25