🌙 The Art of the Minimal Repro Contents What is a minimal repro? Why make a minimal repro? 🪞 For Yourself 🤝 For Others (When You Need Help) 🤖 For AI Tools What Makes a Good Repro? 📝 Steps to Reproduce 🔍 Debug Information 🎬 Show, Don't Just Tell ⚡ One-Click Repros (The Gold Standard) Good Repro vs Bad Repro How to Make a Minimal Repro Option A: Start Fresh (Recommended) Option B: Strip Down 🎉 Plot Twist: You Might Fix It Yourself When a Minimal Repro Isn't Enough The Checklist ✅ Do This ❌ Don't Do This Quick Links Minimal repros are a fundamental tool when debugging.
What is a minimal repro? It is minimal. It contains the least amount of details to be sufficient. Anything that can be removed, is removed. It reliably reproduces the issue. "If you follow these steps exactly, you too will see the issue." Why make a minimal repro? 🪞 For Yourself First-and-foremost, you make repros for you.
Debugging is isolating. You cannot address what you cannot isolate. How can you fix a bug if you don't know where it is?
If a bug is fixed in a forest without a repro, is it even fixed?
How would you know if you even fixed it? This point is profound, so let me spell it out for you:
You have a bug You don't first establish a repro. You try to fix the bug. Now what? Did you even fix the bug? How could you tell? Now you have to go back, undo your fix, and see if the bug comes back. In other words, you then have to go back and create a reverse-repro. You would've saved yourself a lot of time if you had taken a moment to first make a repro. Fixing a bug means that the repro no longer repros.
This is similar to the maxim that you should never optimize without first measuring. If you try to make something faster without first measuring how fast it is, how will you know if you succeeded or made things worse? More importantly: how will you make sexy graphs you can brag about online?
🤝 For Others (When You Need Help) When you ask for help with a messy, complex codebase, you're essentially asking a mechanic to clean out your car before they can diagnose the engine. That's your job. The isolation work is the prerequisite to getting help — not part of the help itself.
A good repro gets you:
Faster responses — Helpers can immediately understand your problem Better answers — They're solving your actual issue, not guessing More willing helpers — Respect for others' time earns goodwill People who help in forums, Discord servers, and GitHub issues are volunteering their time. Respect it.
The XY Problem: Sometimes while making a minimal repro, you'll realize you're asking for help with the wrong problem entirely. You thought you had a layout bug, but actually you're overriding styles elsewhere in your codebase. Read more about the XY Problem →
🤖 For AI Tools Minimal repros aren't just for humans anymore.
Got ChatGPT, Claude, or Copilot? A minimal repro is perfect for pasting into an AI assistant.
The smaller and more focused your code, the better the AI can understand and help. A 2000-line file will confuse it. A 20-line reproduction will get you a precise answer.
Even better, an AI agent can iteratively try to fix the bug, see if the repro still causes the issue, in a tight feedback loop, while you go out to lunch, and you can come back to a fix that's verified by the fact that the repro no longer repros!
Pro tip: you can now use AI to even help you make a minimal repro in the first place! Point it at this website (repro.fyi) and tell it to help you turn your bug into a minimal repro!
What Makes a Good Repro? A great repro puts the other person into the bug as fast as possible. Here's what that looks like:
📝 Steps to Reproduce Write out the exact steps. Don't assume anything is obvious.
Example of good steps Go to the login page Enter any email address Leave password blank Click "Submit" Expected: Validation error appears Actual: Page crashes with white screen
🔍 Debug Information Include the context that helps diagnose:
Error messages — Copy the full text, not just "it says error" Console logs — Open DevTools (F12) → Console tab Network requests — DevTools → Network tab (look for red/failed requests) Crash reports — Stack traces, error codes, anything the system tells you Incognito test — Try in a private/incognito window to rule out browser extensions 🎬 Show, Don't Just Tell A video of you recreating the issue while talking through it is incredibly valuable. Describe:
What you're clicking What you expect to happen What actually happens ⚡ One-Click Repros (The Gold Standard) The absolute best repro is one someone can run instantly:
JSBin / CodePen / JSFiddle — For frontend issues Val Town — For backend/API issues TypeScript Playground — For TypeScript type issues Rollup REPL — For bundler issues GitHub repo — For complex setups (but keep it minimal!) If someone can click a link and see your bug, you've done so much of the work for them. They will know you respect them and their time.
Good Repro vs Bad Repro ❌ Bad bug report "The app is broken. Please fix ASAP."
What's wrong with this?
No steps to reproduce No error messages No expected vs actual behavior No environment info "Broken" could mean 100 different things ✅ Good bug report Environment: Chrome 120, macOS Sonoma, Node 20.10.0
Steps:
Open the dashboard (/dashboard) Click "Export Data" button Select "CSV" format Click "Download" Expected: CSV file downloads
Actual: Nothing happens. Console shows: TypeError: Cannot read property 'map' of undefined at ExportService.js:42
Minimal repro: [CodeSandbox link]
Notes: Works fine with "JSON" format. Only fails with CSV.
Why this is better:
Exact steps anyone can follow Clear expected vs actual Full error message with line number Environment specified Narrowed down to CSV-specific issue Includes runnable reproduction How to Make a Minimal Repro Option A: Start Fresh (Recommended) Create a new project/file/sandbox Add only the code needed to show the bug If you can't reproduce it, that tells you something! Option B: Strip Down Make a copy of your project Delete half the code Does the bug still happen? Yes: Delete half of what remains No: The bug was in what you deleted—put it back and delete the other half Repeat until you have the smallest possible code that shows the bug Another similar debugging technique is to use git bisect to find the offending commit.
🎉 Plot Twist: You Might Fix It Yourself Somewhere in this process, you'll often go: "Wait, why did I write it that way?"
That's the magic. The minimal repro process forces you to understand your own code. And understanding is 90% of fixing.
When a Minimal Repro Isn't Enough Sometimes context matters. A minimal repro might not capture:
Race conditions — Timing-dependent bugs that only appear under load Environment-specific issues — Bugs that only occur on specific OS/browser/hardware combinations Security vulnerabilities — Where the full context is needed to understand the attack vector Data-dependent bugs — Issues that only appear with specific data shapes or volumes In these cases, be upfront: "I couldn't reproduce this in isolation, but here's what I've tried..." and provide as much context as you can about when/how it occurs.
Heisenbugs: Named after Heisenberg's uncertainty principle, these are bugs that seem to disappear or change behavior when you try to observe them. Common causes include timing-sensitive code (the debugger changes timing), memory issues masked by debug builds, or console.log statements that affect execution order. If you suspect a Heisenbug, document when it occurs vs. when it doesn't, and note whether debugging tools affect the behavior.
The Checklist Before sharing your repro, verify each item.
✅ Do This Self-contained — Can someone copy-paste-run it without setup? Include the error — Full error message, not "it doesn't work" Include versions — Node version, browser, OS, package versions Steps to reproduce — Numbered list of exactly what to do Expected vs Actual — What should happen? What happens instead? Actually minimal — Could you remove anything else? Try. ❌ Don't Do This No screenshots of code — I can't copy-paste an image. Give me text. No partial code — "Here's the relevant part" often hides the bug No entire codebases — Your 50-file project isn't a repro "It doesn't work" — Doesn't work how? What did you expect? Nothing is "obvious" — State your environment, steps, everything Quick Links 📚 SSCCE (Short, Self-Contained, Correct Example) — The original guide that inspired this page 🐛 Jam.dev — Capture bug reports with full context 📖 How to Report Bugs Effectively — Simon Tatham's classic guide repro.fyi — Because debugging is isolating, and isolation is your job.
Found this helpful? Share it with someone who sends you "it's broken" messages.
Have feedback or want to contribute? Edit this on Val Town →