Guides · Product
How to handle bug reports for your Minecraft plugin
Where server owners should report plugin bugs, what every report needs, a ready template, and how to triage reports without drowning in them.
A bug report is a gift: someone hit a problem and, instead of uninstalling, told you. The trouble is that most reports arrive as "it doesn't work" in a review, with no version and no log. Here's how to get better reports and handle them without drowning.
Pick one place
Reports scattered across reviews, the discussion tab, DMs and three Discord channels get lost. Choose one main place and say it everywhere (description, plugin.yml, the error message itself):
| Channel | Good for | Watch out |
|---|---|---|
| Discord | Fast back-and-forth, a community | Reports scroll away; use a forum channel with tags |
| GitHub issues | Tracking, templates, linking to fixes | Many server owners don't have an account |
| SpigotMC discussion | Owners are already there | No structure, hard to track |
| In-game | No friction at all, right when it happens | Needs a way to collect it |
Many developers use Discord for conversation and GitHub (or a Discord forum channel) for tracking. Whatever you choose, ask people not to report bugs in reviews: point to the right place in your description and reply to the review with the link.
What every report needs
Most bugs depend on the environment. A report without these takes three messages to start:
- Plugin version and server software and version (Paper 1.21.4, Spigot 1.20.1…).
- Other plugins that might interact (permissions, economy, protection).
- What they did, what they expected, what happened.
- The error from the console, in full, through a paste site like mclo.gs, not a screenshot.
- Their config, if the bug might depend on it.
A report template
Pin this, or use it as a GitHub issue template:
Plugin version:
Server software and version (e.g. Paper 1.21.4):
Other relevant plugins:
What I did:
What I expected:
What happened instead:
Console error (paste on https://mclo.gs and link it):Triage without drowning
- Reproduce first. Same plugin version, same server software, same config. If you can't reproduce it, ask for exactly what's missing.
- Check if it's known. Many reports are the same bug. Merge them and keep a count: three people hitting it means more than one loud one.
- Ask about the version. A good share of reports are already fixed in a newer version. A good update checker reduces these a lot.
- Close the loop. Reply when it's fixed, with the version. People who see their report fixed become your best reviewers.
Reports that carry their own context
The best report is one the owner can send in five seconds, from where the problem happened, that already includes everything above. That's what PluginAnalytics' in-game bug reports and ideas do: the SDK adds /yourplugin report <message> and /yourplugin suggest <message>, and each report arrives in your dashboard with the plugin, Minecraft and server versions, whether it came from a player or an admin, and your plugin's own errors and log lines from the 15 minutes before, with player names, IPs and UUIDs removed. No account, no template, no paste site.
And for the bugs nobody reports at all, error tracking catches them on every server.
Summary
- One main place for reports, said everywhere.
- A template that asks for versions, steps and the full error.
- Reproduce, merge duplicates, check the version, close the loop.
- Make reporting as easy as typing a command, and collect the context automatically.
More guides
Error tracking for Minecraft plugins: find the bug before the 1-star review
How Spigot and Paper plugin exceptions reach the console, why waiting for reports fails, and how to collect, group and fix errors from every server.
4 min readEngineeringUpdate checkers for Spigot plugins, done right
Build a Spigot plugin update checker right: SpigotMC and Modrinth APIs, version comparison, async checks, who to notify and critical updates.
3 min read