Writing a WordPress plugin bug report that support teams can actually act on

If you have ever posted in a WordPress plugin support forum, you know the first reply by heart:

"Can you share your System Info, the steps to reproduce, and confirm the issue happens with only our plugin active?"

That reply costs you a day, sometimes three. The support person isn't stalling. They can't do anything with "checkout is broken since the update, please fix ASAP." They need to see the bug happen on their own test site, and your report is the only map they have.

I build and support a WordPress plugin, and I read a lot of these threads. The ones that get fixed fast all have the same shape. Here it is.

1. One sentence: what you expected vs. what happened

Not "it doesn't work." Two halves:

• Expected: "Clicking Place order with Stripe should go to the thank-you page."
• Actual: "The spinner runs for about 10 seconds, then 'There was an error processing your order' appears. No order is created."

Copy any error text exactly. Screenshots are good. The exact text is better, because people can search it.

2. Steps to reproduce, from a clean start

Write them like a recipe someone else will follow on a fresh install:

1. Add any simple product to the cart.
2. Go to /checkout/ as a logged-out visitor.
3. Choose Stripe, use test card 4242 4242 4242 4242.
4. Click Place order.

Then add one line: does it happen every time, or sometimes? "3 out of 5 tries" is a useful fact. Bugs that happen "sometimes" are often caching, cron or race conditions, and the developer will look in a different place.

Also note who sees it: logged-out visitors only? Admins only? One browser? That one detail can cut the search in half.

3. Versions, all of them

The developer will try to rebuild your setup. Give them the numbers:

• WordPress version
• PHP version
• The plugin's version (and the version where it last worked, if you know it)
• Active theme and its version
• Hosting type if relevant (managed host, object cache, CDN)

You don't have to type this. Tools → Site Health → Info → Copy site info to clipboard gives you all of it. Paste it inside a collapsible block or a code block if the forum supports it. Remove anything private first (the copy is plain text, so read it before posting).

4. Prove it's this plugin (or name the pair)

This is the part most reports skip, and it's the one that matters most.

Every plugin developer has spent hours on a bug that turned out to come from a different plugin. So the first thing they will ask is: does it still happen when only our plugin (plus WooCommerce, if it's a Woo extension) is active, with a default theme?

If you can answer that before they ask, your thread jumps the queue. There are a few ways to get the answer:

• On a staging copy: deactivate everything except the plugin in question, switch to a default theme like Twenty Twenty-Five, test. Then turn plugins back on in halves until the bug returns. Halving is much faster than one by one: 30 plugins take about 5 to 7 rounds, not 30.
• On the live site, without breaking it for visitors: the Health Check & Troubleshooting plugin can disable plugins for your logged-in session only.
• With a conflict tool: I built Culprit Finder for exactly this step (disclosure: I'm the author). It runs the halving for your browser only, asks "is the problem still there?" after each round, and at the end gives you a plain-text report to paste into the support thread. It's free and open source.

Whatever method you use, the answer usually lands in one of three buckets, and each one is worth stating clearly:

What you found	What to write
Happens with only this plugin active	"Reproduces with only X active and Twenty Twenty-Five." The developer now owns it.
Only happens with one other plugin also active	"Only happens when X and Y are both active. Either one alone is fine." This is a conflict. Post it to both plugins' forums and link the threads.
Disappears with a default theme	"Goes away with Twenty Twenty-Five." Now it's a theme issue (or theme + plugin).

That middle row is the one people miss. Two plugins can each work fine alone and break only together, for example both loading a different version of the same JavaScript library, or both hooking the same filter at the same priority. If you only ever test "all on" vs. "one off," you will never see it.

5. The error log, trimmed

If there's a PHP error, it's the single most useful thing you can send. Turn on logging in wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Reproduce the bug once, then open wp-content/debug.log. Post only the lines that appeared at the time of your test, usually a PHP Fatal error or Uncaught line plus the stack trace under it. Not the whole 4 MB file.

For front-end bugs (buttons that do nothing, endless spinners), open the browser console (F12 → Console) and the Network tab, reproduce, and copy any red errors. A failed admin-ajax.php or /wp-json/ request with its response body is gold.

Turn debug mode off again when you're done.

6. What you already tried

A short list saves a round trip:

• Cleared site cache and CDN cache
• Re-saved permalinks
• Tested in a private window
• Rolled the plugin back to 4.2.1 → works; 4.3.0 → broken

The last line is the best clue you can give a developer. It points straight at one release.

A template you can paste

**Expected:** 
**Actual:** (exact error text)

**Steps to reproduce:**
1.
2.
3.
Happens: every time / sometimes (x of y tries)
Who sees it: visitors / logged-in / admins / one browser

**Isolation:**
- With only [this plugin] (+ WooCommerce) and a default theme: yes / no
- Conflicts with: [other plugin + version], or "none found"

**Versions:** WP __ · PHP __ · plugin __ (last working __) · theme __
(Site Health info attached below)

**Errors:** (debug.log lines / console errors)

**Already tried:**
- 

Why this works

Support teams triage. A thread with a clear expected/actual, clean steps, versions, and an isolation result can be reproduced in ten minutes, so it gets picked up first. A thread that says "broken, urgent" waits for a back-and-forth that can take days.

You're not doing their job for them. You're giving them the one thing only you have: your site.

---

If you maintain a plugin: consider pinning a version of this template in your support forum. The reports you get back will be better on day one.