What Is a Minimal Reproducible Example? A Practical Guide

A minimal reproducible example (MRE) is the smallest, self-contained set of code, data, and steps that reliably triggers a bug on someone else's machine. It strips a problem down to only the parts required to make it fail, so whoever investigates can run it, watch the failure, and fix it without guessing. An MRE has three defining properties: it is minimal (nothing extra), complete (nothing missing), and reproducible (it fails the same way every time).

What does "minimal reproducible example" mean?

The term is often shortened to MRE, and you'll see two older names for the same idea: MCVE (minimal, complete, and verifiable example) and SSCCE (short, self-contained, correct example). They all describe the same target — the smallest case that still demonstrates the problem. Break the name into its three parts:

1. Minimal. Every line, file, and step that isn't needed to reproduce the bug has been removed. If deleting something doesn't stop the failure, it doesn't belong.
2. Complete. Everything that is needed is present. Someone can take your example, run it as-is, and see the failure — no missing imports, no undefined variables, no "assume you have X set up."
3. Reproducible. It fails consistently, not intermittently. If it only breaks sometimes, you either capture the exact conditions that make it break or you note the flakiness explicitly.

Why does a minimal reproducible example matter?

Most of the time a bug spends waiting is spent on the back-and-forth: "Can you share your version?" "What did you click?" "I can't reproduce this." An MRE collapses that loop into a single artifact. Three concrete reasons it speeds up a fix:

• It removes ambiguity. A runnable case can't be misread the way prose can. Whoever picks up the ticket sees the exact failure instead of reconstructing it from a description.
• It isolates the cause. The act of shrinking the example is itself debugging. Very often you find the culprit while cutting away everything around it — and sometimes realize the bug was in your own setup before you ever file it.
• It becomes the regression test. A minimal failing case is most of the work of a test that proves the fix and stops the bug from coming back. The MRE you attach today is the test you commit tomorrow.

How do you create a minimal reproducible example?

Reduction is the core technique: start from the code that fails and remove things until you can't remove any more without the bug disappearing.

1. Reproduce it yourself first. Confirm you can trigger the bug reliably before trying to shrink it. If you can't reproduce it on demand, note the conditions under which it does appear.
2. Copy, don't edit in place. Work on a duplicate so aggressive deletion can't damage your real project. You're going to remove most of it.
3. Delete in halves. Cut roughly half the remaining code or steps and re-run. If the bug still shows, keep that half and repeat. If it vanishes, restore and cut a different part. This binary search converges fast.
4. Inline the dependencies. Replace external services, private data, and large frameworks with the smallest stand-in that still reproduces the failure — a hardcoded value, a tiny fixture, a two-line stub.
5. Sanitize the data. Swap real customer records for the minimum synthetic data that triggers the bug, so the example is safe to share.
6. Verify on a clean environment. Run your final example somewhere fresh — a new folder, a container, a fresh browser profile. If it fails there too, it's genuinely complete. If it doesn't, something in your local setup was part of the cause, and that's worth knowing.

What to include alongside the example

The runnable code is the centerpiece, but an MRE lands best when it ships with the context that makes it easy to run and interpret:

• Exact steps to reach the failure, numbered, with no assumed knowledge.
• Expected vs. actual — what should happen, and what happens instead.
• Environment — versions, OS, browser, and any relevant configuration.
• Evidence — the error message or stack trace, plus a screenshot, console output, or failing network request where the bug is visual or in the browser. (See our guide on writing a bug report developers act on for the full checklist.)

Common mistakes that break an MRE

Even a well-intentioned example fails its job when it slips on one of these:

• Too much. Pasting the whole file or repo instead of the failing slice. The reader has to find the bug before they can fix it.
• Too little. Trimming so hard that the example no longer runs — a missing import or an undefined variable, and the reader can't even reach the real bug.
• Not actually reproducible. "It sometimes fails" with no captured conditions. If it's a race or timing issue, say so and describe when it appears — that's still useful signal.
• Environment left out. The example runs fine for the reader because the bug depended on a version or setting you never mentioned.

Where tooling helps

The hardest part of an MRE is usually capturing the environment and evidence accurately — the details people forget or mistype from memory. In-app bug reporting tools attach the current URL, console, network activity, and environment automatically at the moment a bug is flagged, so the reproduction context is captured rather than reconstructed later. Klavity's Snap does this from a right-click, giving you the environment and evidence half of an MRE for free — you supply the minimal steps, and the state travels with the report. It's the difference between "works on my machine" and a case anyone can run.