Install and configure your plugins without breaking your server

Installing a plugin means dropping a file into a folder. What brings servers down is everything done before and after.

Only download from four places

SpigotMC, Hangar (PaperMC's official repository), Modrinth, and the developer's GitHub releases. Nothing else.

Sites offering "free premium" versions distribute modified .jar files. A plugin has every right over your server and the machine hosting it: it's the easiest way in to your database and your backups. A paid plugin you don't want to pay for, you do without.

Check compatibility before, not after

Two numbers must match:

• The game version. A plugin advertised for 1.20 will often work on 1.20.4, rarely on 1.21. The plugin's page lists the tested versions: trust it.
• The platform. Paper accepts Spigot and Bukkit plugins. The reverse isn't true: a plugin requiring Paper's APIs won't start on Spigot.

Dependencies

Three plugins come back as dependencies of everything else:

• Vault: the go-between for economy, permissions and the plugins that use them.
• PlaceholderAPI: the %player_name% variables and the like, used by tab lists, scoreboards and messages.
• ProtocolLib: for plugins that manipulate network packets.

A plugin asking for a missing dependency clearly writes Unknown dependency at startup and disables itself. It's the easiest error to read in all of Minecraft: make the most of it.

The first startup is for generating configurations

The right sequence is always the same:

1. Stop the server. Cleanly, with stop in the console, never by killing the process.
2. Drop the .jar into plugins/.
3. Start. The plugin creates its folder and default configuration.
4. Stop again, edit the configuration, restart.

Editing a configuration while the server is running is pointless: it has already read it, and may write over it when it stops.

YAML: the three traps

Configuration files are in YAML, and YAML is unforgiving.

• Tabs are forbidden. Spaces only. Half of could not load config errors come from this.
• Indentation carries meaning. Two extra spaces move a setting into another section.
• Ambiguous values go in quotes. yes, no, on, off are read as booleans; a password starting with a digit also wants quotes.

Run every modified file through a YAML validator before restarting. It takes ten seconds and avoids a server refusing to come up at midnight.

Permissions: groups, never players

Install LuckPerms. There's been no debate on this for years.

And give permissions to groups, not players. A server where each moderator got their rights by hand becomes impossible to audit after three months: nobody knows who can do what any more, and the day a moderator leaves, orphaned rights remain.

Three or four groups are enough to start: default, vip, moderator, admin. Each one inherits from the previous.

Keep operator status for yourself alone, and never for a group. op bypasses all permissions, including those you carefully removed.

Why /reload is a bad idea

/reload reloads plugins without restarting the server. It's handy, and it's the cause of a remarkable share of unexplained bugs: plugins keep references to objects from the previous load, scheduled tasks duplicate, and memory leaks set in.

Many plugins offer their own reload command: /luckperms reload, /essentials reload. Those are safe, because the plugin knows what it's reloading. Use them. For everything else, restart.

Find the faulty plugin in four restarts

The server crashes, the console is unreadable, and you have twenty-five plugins. Proceed by halving:

1. Move half the plugins to a separate folder. Start.
2. If the problem disappears, the culprit is in the half removed; otherwise, in the half that stayed.
3. Repeat on the guilty half.

Twenty-five plugins come down to one in five tries. It's much faster than reading the stack trace, and it works even when the error message names nobody.

Before that, still take thirty seconds to open logs/latest.log and look for the first line containing Caused by: half the time, the plugin's name is written there.

Keep a list

A text file, next to the backups, with for each plugin: its name, its version, where it comes from, and what it does on your server.

The day you move machines, upgrade versions, or take the server back after six months, this list is worth every folder dig. And version the plugins/*/config.yml folder: knowing what changed the day before everything broke is the shortest path to a fix.

---

Your server is running and your plugins are in place? List it, and remember to connect Votifier to reward votes automatically.