Preflight

Preflight
Tells you which of your plugins will break before you upgrade, by reading their bytecode.


The problem

A plugin's page says it supports the version you're moving to. It compiles fine. It loads fine.
Then the first player who opens a menu gets kicked, because a Bukkit type quietly changed from a
class to an interface between versions and the plugin's compiled code still calls it the old way.

Nothing on that download page could have warned you. "Supports 1.21" was typed by hand, months
ago, and the break doesn't live in the plugin — it lives in the gap between the plugin's compiled
code and the version you're about to run.


What Preflight does

It opens every jar in your plugins folder and reads the compiled code — not the download page,
not plugin.yml. For each API call, field and type the plugin references, it checks
whether that thing still exists in the version you're targeting, the same way the JVM would look
it up when the server runs.

Then it tells you what would happen, and where: the exact class, method and line.

in com/example/plugin/MenuHandler.open line 142

No dependencies, nothing to set up, and it never talks to the plugin's author or download page.
Everything it needs about each Minecraft version is bundled inside the jar.


What you get

A colored summary in console or chat, a full report written to disk, and a link to read that
report as a web page:



The page gives you a summary, a severity filter, a search box, and one collapsible section per
plugin with its own link you can paste into a ticket. It works on a phone and follows your light
or dark theme.

Only the report is uploaded — plugin names, versions, and what would break. Nothing about your
players, worlds or configuration. Links are long and random, nothing is listed anywhere, and
reports are deleted after 30 days. Preflight also sends anonymous usage stats (bStats: Minecraft
version, Java version, a player-count bucket, plugin version) and asks SpigotMC once at startup
whether a newer version exists, naming only its own resource id — neither knows anything about
your players, worlds or scanned plugins. Set share.enabled, metrics
or check-for-updates to false in config.yml to turn
any of them off; with all three off, nothing ever leaves your machine. You can also point
share.endpoint at your own host.

What the severities mean

Severity	What it means
BREAK	The plugin will not load at all. The server refuses it, or the class fails the moment it's loaded.
LIKELY	The plugin loads, but the affected code throws the first time it runs — when someone opens that menu, runs that command, triggers that event.
NMS	The plugin reaches into server internals, which are rebuilt every version. Not a prediction, just something to keep an eye on.
NOTE	Worth knowing, but not a failure — including calls the plugin already wraps in its own try/catch.

The line between BREAK and LIKELY isn't a guess about confidence — it's how the JVM actually
works. Only a class's parent types are resolved when it loads; everything else resolves the first
time that particular line of code runs. So a plugin can be badly broken and still start up
perfectly, which is exactly what makes this kind of failure so annoying to find.


Two versions, not one

"What's broken on 26.2" is the wrong question, because some of it is already broken today and
you've been living with it. The question that decides an upgrade is what it costs you.

Give Preflight the version you run now and the one you're considering, and it splits the results
three ways: new problems the upgrade causes, problems you already have either way, and problems
the upgrade fixes.



Commands

Permission preflight.use (default: op). The scan runs off the main thread, so it
won't freeze your server.

There's also a standalone command-line jar, for checking a backup or a plugins folder without
running a server at all — handy in CI, or before you touch someone else's server:

It takes a single jar as well as a folder, so you can check one freshly built plugin. The CLI
never uploads anything.


Tested on real servers

Measured on a live survival server running 1.21.11 with 72 third-party plugins — the ones in the
screenshots above, a mix of free and premium. Scanned against 26.2 it takes a few seconds and
reports 43 plugins that would fail once the affected code runs, 4 that touch server internals,
25 clean, and none that fail to load outright: 404 findings in total, which is exactly why the
report page has a filter and collapsible sections rather than being one long list.

Comparing 1.21.11 to 26.2 on that same folder is the more useful number: 23 new problems caused
by the upgrade, 28 already broken today either way, and 5 that the upgrade actually fixes. Most
of what a plain scan shows you is not the upgrade's fault.

The predictions were also checked against reality on a smaller test server. A real 26.2 server
was booted with a 23-plugin folder. Three plugins failed. Two failed for the same reason — they
read the server's version string and ran it through a numeric parse, and 26.x changed the shape
of that string — and Preflight had already found both offline, naming the exact class, method
and line, before either was ever started. Not one plugin failed to link.

The third failure is one Preflight did not catch, and it's the honest reason for the section
below. It didn't break on a missing API at all — a library it depends on failed during its own
startup, for reasons no bytecode scan can see, and took the plugin with it.


What it can't see

A tool that predicts breakage and oversells itself is worse than no tool. Read this before
trusting a clean report.

• A plugin's own logic. Preflight checks whether the things a plugin calls still exist.
  It largely can't see a plugin breaking on its own behaviour — a renamed enum value, a config it
  can't read, a changed return value it mishandles. On that live 26.2 boot, every failure was of
  this kind. One common case is covered: reading the server version and parsing it as a number.
• Reflection. A method looked up by name at runtime is invisible. A class name passed to
  Class.forName can be spotted, but only as a hint to go look — never as a
  prediction.
• Whether the code ever runs. A LIKELY finding is a call that would throw if reached.
  If it sits behind a version check that skips your server, it never fires.
• Behaviour changes. A method can keep its exact shape and quietly do something different.
  Preflight checks the shape.
• Plain Spigot. The bundled data comes from the Paper API, which is a superset. On a pure
  Spigot server, Paper-only calls won't be flagged. Over-reporting on Paper, which nearly everyone
  runs, would be the worse mistake.

A clean report means nothing was found by this method. It is a good reason to feel better about
an upgrade, not a guarantee — still test.


Bundled versions: 1.20.1, 1.20.6, 1.21, 1.21.4, 1.21.8, 1.21.11, 26.1, 26.2. The jar is about
1.2 MB with all of them inside. Full command reference and troubleshooting: Documentation tab.