Guides · Engineering

Update 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.

Updated 9 October 2026 · by Skilled · 3 min read

Most bugs you've already fixed keep hurting you, because servers keep running the old version. An update checker closes that gap: when you release, admins find out. Done badly, it spams consoles, blocks startup or nags every player. Here's how to do it well.

Where to read the latest version

SpigotMC has a simple endpoint that returns the latest version string of a resource as plain text:

https://api.spigotmc.org/legacy/update.php?resource=12345

12345 is the number at the end of your resource's URL. The value is the version you typed when you posted the update, so keep those consistent with your plugin.yml.

Modrinth returns the versions of a project, newest first:

https://api.modrinth.com/v2/project/your-slug/version

Read version_number of the first one. Modrinth asks for a User-Agent that identifies your project.

Both APIs can lag a little behind a release, and both can be down. Your plugin must work the same either way.

Check off the main thread

Never make an HTTP request on the main thread: a slow response freezes the server. Check asynchronously, on startup and then every few hours:

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    try {
        HttpURLConnection c = (HttpURLConnection) new URL("https://api.spigotmc.org/legacy/update.php?resource=12345").openConnection();
        c.setConnectTimeout(5000);
        c.setReadTimeout(5000);
        String latest = new String(c.getInputStream().readAllBytes(), StandardCharsets.UTF_8).trim();
        if (isNewer(latest, plugin.getDescription().getVersion())) this.latest = latest;
    } catch (IOException ignored) {
        // offline or the API is down: try again next time
    }
});

(On Folia, use the async scheduler instead: see making your plugin Folia-compatible.)

Compare versions as numbers

String comparison says 1.10.0 is older than 1.9.2. Compare each number in turn:

static boolean isNewer(String latest, String current) {
    String[] a = latest.split("[^0-9]+"), b = current.split("[^0-9]+");
    for (int i = 0; i < Math.max(a.length, b.length); i++) {
        int x = i < a.length && !a[i].isEmpty() ? Integer.parseInt(a[i]) : 0;
        int y = i < b.length && !b[i].isEmpty() ? Integer.parseInt(b[i]) : 0;
        if (x != y) return x > y;
    }
    return false;
}

Never tell someone running a newer version (a dev build, say) to "update" to an older one.

Tell the right people, once

• Console: one line on startup when an update exists. Not every check.
• In game: only to players with a permission (say yourplugin.update, default op), when they join. Never to regular players.
• Include the link to your resource page, and what changed if it's short ("fixes data loss with MySQL").
• Let owners turn it off in the config. Some networks pin versions on purpose.

Critical updates

Some releases matter more than others: a dupe exploit, data loss, a security fix. Those deserve a stronger message (a warning in the console, a red line for admins) even if the owner usually ignores updates. Decide it per release, not per check, and say why: "Versions below 2.3.1 can lose player data on restart".

Without writing it yourself

PluginAnalytics' update notices do all of the above with no code beyond the SDK: the latest version is read from SpigotMC or Modrinth (or set by hand), admins with the permission get your message on join, you set a minimum version below which the notice becomes a warning, and you change the message in the dashboard without a new release. You also see how many servers are still on each version, which tells you whether people actually update.

Checklist

• Read the version from SpigotMC or Modrinth, with timeouts, off the main thread.
• Compare numbers, not strings.
• One console line; in-game only for admins with a permission.
• Link to the resource and say what changed.
• An option to turn it off.
• A clear warning for critical updates.

More guides