Here's a secret: Creating a minimal repro often solves your own bug before you even ask for help. Seriously. The process of isolating a problem is debugging.

Isolation is debugging. You can't fix what you can't find.

Think of it like a bisect: you remove code until the bug disappears. Then you add back the last thing you removed. That's your culprit. This is how experienced developers debug—not by staring at thousands of lines of code, but by systematically narrowing down the problem.

The XY Problem: Sometimes while making a minimal repro, you'll realize you're solving the wrong problem entirely. You thought you had a CSS bug, but actually you're fighting the browser's default styles. Read more about the XY Problem →

When you ask for help with a messy, complex codebase, you're essentially saying: "Here's my whole room. Find my keys."

A minimal repro says: "Here are my keys on an empty table. Why won't they turn?"

Asking someone to isolate your bug for you is like asking a painter to clean your room before they can paint the walls. That's your job. The isolation work is the prerequisite to getting help—not part of the help itself.

People who help in forums, Discord servers, and GitHub issues are volunteering their time. Respect it.

A great repro puts the other person into the bug as fast as possible. Here's what that looks like:

Write out the exact steps. Don't assume anything is obvious.

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

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

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 the work for them.

1. Create a new project/file/sandbox
2. Add only the code needed to show the bug
3. If you can't reproduce it, that tells you something!

1. Make a copy of your project
2. Delete half the code
3. 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
4. Repeat until you have the smallest possible code that shows the bug

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.

Before sharing your repro, verify each item. Click any item to link directly to it.

• 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.

• 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

• The XY Problem — Are you solving the right problem?
• SSCCE — 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 isolating is your job.

Found this helpful? Share it with someone who sends you "it's broken" messages.