PlugTrace | Catch Broken Plugin Updates Before Players Do [1.20-26.x]

⚡ Your server reached Done. Did everything actually survive the update?

A lot of bad server updates don't crash anything.

Paper starts normally, the console reaches Done, players can join, and it looks like the maintenance went fine.

Then somebody notices a few minutes later that a plugin never enabled, a command disappeared, a dependency isn't there anymore, a world didn't load, or something else changed during the restart.

PlugTrace is for finding that stuff before you have to hear about it from a player.

It keeps track of your server before and after risky restarts, checks the things that were supposed to survive the update, and keeps enough context around each restart to help you figure out what actually changed.

Instead of only seeing this:

you can check:

and get an actual result for the current deployment:


The result is backed by the checks, changes and incidents PlugTrace recorded around that restart.

If you already use spark, keep using it. spark is great when the server is lagging. PlugTrace is for the other annoying situation: you changed something, restarted, and now part of the server isn't the same.



What PlugTrace actually checks

PlugTrace is mainly interested in the quiet regressions that are easy to miss after maintenance.

• Plugins that disappeared or failed to enable
• Commands that existed before the restart but are now missing
• Missing dependencies or registered services
• Worlds that were expected but are no longer available
• Plugin JARs being added, removed or replaced
• A JAR changing while still reporting the same version
• Config reset or deletion evidence
• New severe startup problems
• Problems that only appear after startup has already finished

It also keeps the useful surrounding information instead of giving you one red/green light with no explanation.

That can include failed checks, JAR differences, expected-state changes, incident history, deployment history and suspect information when there is enough evidence to support one.

So instead of:

"Something broke after I updated plugins."

you can get much closer to:

"These files changed during this restart, these checks stopped passing, and these issues appeared afterward."

That is usually a much better place to start debugging.


Start while the server is healthy

PlugTrace is much more useful if it already knows what your working server looked like.

After installing it on a healthy server, a normal first setup looks like this:

The expected-state capture records things PlugTrace can check again later, such as plugins, commands, worlds and registered services.

After that, maintain your server normally.

Update plugins, replace JARs, change configs, upgrade Paper, change dependencies or do whatever else you were planning to do.

Restart the server, then run:

That's the main PlugTrace workflow.




⚠ A checkpoint is not a server backup.

It is a reference to a state you knew was working.

Keep normal backups for worlds, databases, configs and anything else you actually need to restore if something goes wrong.


⚡ `/plugtrace status` is the command you'll use most

For normal use:

If the result looks wrong, you can go further:

✓ HEALTHY

The important checks passed and PlugTrace has enough information to consider the deployment healthy.

⚠ DEGRADED

Something changed or regressed, but PlugTrace does not have evidence of a critical failure.

✕ FAILING

One or more critical checks failed.

The server process may still be running perfectly fine. This status is about whether the deployment itself still matches what you expected.

? UNKNOWN

PlugTrace does not have enough reliable information yet to make a confident call.

UNKNOWN is not an error state that PlugTrace tries to hide.

If the evidence is weak, it says so instead of picking a plugin and pretending that must be the cause.




See what changed around the restart

When something breaks, this is usually the next command worth running:

The diff helps narrow down what was different between the state you trusted and the restart that caused trouble.

That can answer questions like:

• Was a JAR added?
• Was something removed?
• Did a plugin artifact change?
• Did an expected command disappear?
• Did an expected service disappear?
• Did new incident evidence start appearing after this restart?

If you want PlugTrace's strongest evidence-backed suspect:

Sometimes it can narrow things down nicely.

Sometimes several things changed at once and there isn't enough evidence to confidently name one culprit.

In that case, PlugTrace leaves it unresolved instead of making something up.

The diff and failed checks are still useful even when there is no single obvious cause.


⏱ Some problems happen after startup

Not every plugin fails immediately.

A plugin can enable successfully and throw a severe error a few seconds later.

A dependency can look fine until another plugin tries to use it.

A scheduled task can fail after players are already online.

PlugTrace can keep observing the deployment after the server becomes ready so those problems are not automatically ignored just because Paper already printed Done.

A clean startup is useful. It just isn't proof that every part of the update worked.


Need help? Share the report instead of dumping your whole console

If you need to send the problem to another admin, a plugin developer, your host or somebody in Discord, PlugTrace can build a focused report for that deployment.

Preview it first:

If you decide you actually want to upload it:

PlugTrace returns a hosted plugtrace.dev link that you can send similarly to a spark profile.




Hosted sharing only happens after an administrator explicitly runs the share command.

Reports are redacted before upload, encrypted and temporary.

The normal PlugTrace workflow does not depend on the hosted service.

More details are available here:

PlugTrace privacy documentation →


Local-first

You do not need a PlugTrace account to use the plugin.

You do not need a subscription.

You do not need to keep a cloud dashboard connected.

Your players do not need to install anything.

Deployments, checks, checkpoints and local reports stay with the server.

PlugTrace also includes an optional local web interface if you prefer browsing deployment information outside chat/console.

The hosted side only matters when you deliberately create a share link.


↩ Recovery tools are there when you need them

When PlugTrace has the local evidence required to do it safely, it can help prepare a conservative restore plan.

Recovery is review-first rather than "something failed, automatically roll everything back."

PlugTrace does not automatically restore your world or database and it is not meant to replace proper backups.

The full restore workflow is documented here:

Read the PlugTrace documentation →


Installation

1. Download PlugTrace and place the JAR in:

2. Perform a clean restart.

3. Make sure PlugTrace loaded correctly:

4. While the server is still healthy, create your baseline:

5. After your next risky restart:



Compatibility

✓ Paper
✓ Purpur
✓ Folia
✓ Spigot
✓ Minecraft 1.20 → 26.x
✓ Server-side only
✓ No client mod required


Free and open source

PlugTrace is free and open source under the Apache License 2.0.

There is no required account, paid edition or required cloud service for the core workflow.

If you want to look through how PlugTrace works, report a bug or contribute something, the source is public.


Usage statistics

PlugTrace uses bStats for anonymous usage metrics.


The graph above is loaded directly from bStats and shows the current public usage statistics for PlugTrace.

Server owners can disable bStats globally through the normal plugins/bStats/config.yml configuration.