PluginCatcher: Your Server's Watchdog Against Sneaky Crashes
Running a Minecraft server is a balancing act. You juggle plugins, player expectations, and the ever-present dread of a sudden, unexplained crash. Among the most frustrating culprits is the ConcurrentModificationException, or CME, a threading error that can bring your world to a halt. That is where PluginCatcher steps in, not as a magic fix, but as a sharp-eyed development tool that sniffs out risky plugin behavior before it causes disaster.
What Exactly Is PluginCatcher?
PluginCatcher is a specialized plugin crafted for server owners and developers who want to peer under the hood of their server's operations. It does not patch bugs or rewrite code; instead, it monitors the main server thread for asynchronous calls that could trigger CMEs. The Minecraft server handles almost everything on one primary thread, meaning that most Bukkit API methods are not safe to call from other threads. When a plugin carelessly fires an API call from an async event like AsyncPlayerChatEvent, it can collide with the server's internal collections, leading to a crash. PluginCatcher actively watches for these dangerous interactions and logs them in detail.
Why ConcurrentModificationException Happens
To appreciate what PluginCatcher does, you need to understand the root cause. The server iterates over lists, maps, and sets constantly—tracking entities, processing chunks, handling packets. These collections are not thread-safe. If an asynchronous task modifies one while the main thread is reading it, the server throws a CME and often shuts down. Common triggers include:
- Calling
Player.sendMessage()inside an async chat event listener. - Modifying world blocks from a scheduled task without synchronizing back to the main thread.
- Teleporting entities in response to a network event that runs off the main thread.
PluginCatcher does not catch every possible scenario, but it reliably flags a large number of these patterns, giving you a head start on debugging.
How the Plugin Works Its Detective Magic
Once installed, PluginCatcher imposes a slight performance overhead—this is intentional. It hooks into the server's execution to inspect stack traces whenever a potentially risky call is made. By comparing the stack trace lines against the loaded classes of all plugins, it attempts to identify which plugin triggered the alert. If a match is found, it logs the plugin name and version. If not, it reports the source as unknown. This guessing is purely for convenience; you should always verify the stack trace manually.
For server admins who want a streamlined experience when adding tools like this, the foxygame.net launcher provides a convenient, flexible, and modern Minecraft launcher where you can download mods right from the menu, making it easy to keep your server toolkit up to date without manual file hunting.
Diving Into Configuration
PluginCatcher keeps things simple with just two configuration values. The first, onlydangerous, defaults to true. In this mode, the plugin only reports calls that are almost certain to crash the server. If you set it to false, it expands its watch to include less critical async calls that might cause issues on your own asynchronous threads, such as data corruption or race conditions. The second value is meow. When set to true, it adds a feline twist to the plugin's personality—exactly what you would expect from a developer with a sense of humor.
Reading the Output
All findings are written to a file named async.log inside the PluginCatcher folder. The plugin also prints a single line to the server console whenever it detects and logs an issue. If the log stays empty, congratulations—no potential problems have been spotted yet. When an entry does appear, it contains:
- The suspected plugin name and version (or "unknown source").
- A full stack trace showing the exact method calls leading to the risky behavior.
- A timestamp to correlate with other server events.
This information is gold for developers. You can trace the offending code back to a specific line, determine why it was called asynchronously, and refactor it to run on the main thread using Bukkit.getScheduler().runTask() or similar synchronization techniques.
Who Should Use PluginCatcher?
Server owners who are not comfortable reading stack traces might find PluginCatcher overwhelming. It is not a plug-and-play fix; it is a diagnostic instrument. If you are experiencing mysterious crashes and have a developer on hand, share the async.log with them. Developers, on the other hand, will find it invaluable for stress-testing their own plugins. By running PluginCatcher on a test server with your plugin active, you can catch threading mistakes early in the development cycle.
Limitations and Best Practices
Remember that PluginCatcher is not omniscient. It cannot detect every asynchronous call that might lead to a CME, especially those that involve indirect collection modifications or complex plugin interactions. Also, the slight performance hit means you should not run it indefinitely on a live production server. Use it as a temporary diagnostic tool, then disable it once you have resolved the flagged issues. Always treat the plugin guessing as a starting point; the stack trace is the definitive evidence.
Final Thoughts
PluginCatcher fills a narrow but critical niche in the Minecraft server ecosystem. It empowers developers and attentive admins to proactively hunt down threading bugs that would otherwise manifest as random, frustrating crashes. By logging detailed stack traces and pinpointing suspect plugins, it turns hours of guesswork into a focused debugging session. Pair it with a solid understanding of Bukkit's threading model, and you will keep your server running smoothly, block by block.