What Is a Deterministic Failure? Explained
A deterministic failure happens on every run because its cause is fixed, in the code, configuration, or inputs, not in the transient state of the environment.
Deterministic failures are, paradoxically, the good kind. They are reproducible, which means you can investigate them, find the cause, and fix it with confidence. The defining contrast is with transient failures, which come and go and are best handled by retrying.
The defining property: reproducible
A deterministic failure reproduces every time you run the same job with the same inputs. That consistency is exactly what makes it diagnosable: you can reproduce it locally, bisect it, and verify a fix. Nothing about the environment is involved in whether it happens.
Typical causes
- A failing test assertion: the code genuinely does not do what the test expects.
- A compile or type error that fails identically every time.
- A missing file, dependency, or environment variable.
- A misconfiguration that is wrong on every run.
Why retries do not help
Retrying a deterministic failure is futile by definition: the same inputs produce the same failure, so a second attempt fails identically. Worse, retrying it wastes minutes and can mask the real signal. Deterministic failures should fail fast and loud.
Telling it apart from transient
The single best diagnostic is reproducibility. If the failure recurs on every run, it is deterministic and needs a fix. If it comes and goes, it is transient and a retry is appropriate. Correctly classifying a failure determines whether you debug it or retry it.
The Latchkey angle
Latchkey self-healing managed runners are conservative by design: they retry transient and mechanical failures so a one-off blip does not fail your build, but they let deterministic failures fail fast, because retrying a real code bug only delays the fix.
Key takeaways
- A deterministic failure reproduces on every run with the same inputs.
- Its cause is in the code, configuration, or inputs, not the environment.
- Retries do not help; deterministic failures should fail fast.
- Reproducibility is the key test for transient vs deterministic.