Installing and managing Minecraft plugins

Plugins are .jar files that go in the plugins folder of a Paper, Purpur, or Spigot server, and are loaded when the server starts. The two things that go wrong most often are installing a mod on a server that only takes plugins, and installing a plugin built for a different Minecraft version, so check both before you copy anything across.

Where plugins go

The server creates plugins/ in its own directory on first start. Following the install guide, that is /home/minecraft/server/plugins/.

• One .jar per plugin, dropped in as-is. Do not unzip it.
• On first start, most plugins create their own folder inside plugins/ holding a config.yml and any data files. Edit those after the first run, not before, because a plugin usually overwrites a config it did not generate.
• The files must be readable by the user the server runs as.

Copying a jar up from your own machine:

scp Plugin.jar minecraft@203.0.113.10:/home/minecraft/server/plugins/

If the minecraft account has no SSH key of its own, upload to your own home directory instead and move it into place:

sudo mv Plugin.jar /home/minecraft/server/plugins/
sudo chown minecraft:minecraft /home/minecraft/server/plugins/Plugin.jar

See Connecting to your server if you have not set up SSH file transfer yet.

Then restart the server. Not /reload, for reasons in Updating a plugin below.

Plugins are not mods

This is the distinction that wastes the most time. A Bukkit API plugin and a Fabric or Forge mod are different formats loaded by different code, and neither server will load the other's files.

Symptoms of getting it wrong:

• A mod dropped into plugins/ on Paper fails at startup, and the log says the jar contains no plugin descriptor.
• A Bukkit plugin dropped into mods/ on Fabric is either ignored or reported as an invalid mod.
• A Bukkit plugin in a proxy's plugins/ folder does not load, because a proxy has no world and a different API.

Two more things worth knowing. Client-side mods such as shaders and minimaps are installed by each player in their own client and have nothing to do with the server. And hybrid servers that claim to run plugins and mods together exist, but they trail the upstream projects on version updates and are supported by neither, so they are a last resort rather than a way to have both.

If you need both plugin features and mod features, decide which ecosystem your must-have features live in and build the server around that. See Running a Minecraft server.

Matching a plugin to your server

Three things have to line up: the platform, the Minecraft version, and the Java version.

Platform. From the table above. A plugin page will say Spigot, Paper, or Bukkit for the plugin ecosystem, and Fabric, Forge, or NeoForge for the mod one.

Minecraft version. Every plugin page lists which versions it supports. The Bukkit API itself is fairly stable across versions, so a well-behaved plugin often keeps working after a Minecraft update. A plugin that reaches into server internals to do something the API does not expose usually breaks on every single version bump, and those are the ones that crash rather than warn. To see what your server actually is:

/version

Java version. A plugin compiled for a newer Java than your server runs on fails to load with an UnsupportedClassVersionError. This is uncommon on a current setup but shows up when running older Minecraft on Java 8. See the version table in Installing a Minecraft server on Linux.

Dependencies. Many plugins need another plugin present. A hard dependency stops the plugin from enabling at all when it is missing, and the log says which one it wanted. Shared libraries and permissions plugins have to match your server version too, so update them alongside.

Installing a plugin

1. Check the version and platform

   Confirm the plugin lists your exact Minecraft version and your server software before you download.

2. Back up first

   Take a copy of the world and the plugins folder. See Backups. A plugin that writes to the world can make changes a simple uninstall does not undo.

3. Stop the server

   ShellCopy

   sudo systemctl stop minecraft

4. Copy the jar in and fix ownership

   ShellCopy

   sudo mv Plugin.jar /home/minecraft/server/plugins/
   sudo chown minecraft:minecraft /home/minecraft/server/plugins/Plugin.jar

5. Start it and read the log

   ShellCopy

   sudo systemctl start minecraft
   sudo journalctl -u minecraft -f

   You are looking for the plugin being enabled by name and version, and for any warning underneath it. A plugin that failed to load says so at startup and then never mentions itself again, which is missed often if you only check whether the server came up.

6. Configure it, then restart again

   Edit the config the plugin generated in its own folder, then restart so it is read. Test the feature you installed the plugin for before you move on to the next one.

Install plugins one at a time on a server you care about. Five at once means five suspects when something breaks.

Updating a plugin

The safe sequence:

1. Read the changelog for breaking configuration changes and for the minimum server version it now needs.
2. Back up the world and the plugin's own config folder.
3. Stop the server.
4. Move the old jar out, do not delete it. Keep it somewhere like ~/plugins-old/. Rolling back is then copying one file.
5. Copy the new jar in and fix ownership.
6. Start and watch the log, then test the feature.

Update the server jar and your plugins in separate steps. If you replace Paper and six plugins in one go and the server will not start, you have no idea which one did it.

Spotting a plugin that is causing trouble

It is lagging

Profile it. That is covered in Optimising a Minecraft server, which shows how to read a spark profile and attribute main-thread time to a plugin by name.

It will not start, or it crashes

The log is the source of truth:

sudo journalctl -u minecraft -n 200

Or, in the server directory, logs/latest.log for the current run and the gzipped files beside it for previous ones.

Read from the first error, not the last. A single failure at startup produces a cascade of later errors from everything that depended on it, and the last line on the screen is usually the least informative one.

If nothing obvious names itself, bisect:

1. Move half the plugins out

   ShellCopy

   sudo -iu minecraft
   mkdir -p ~/plugins-off
   mv ~/server/plugins/*.jar ~/plugins-off/

   Then move half of them back and start the server.

2. Halve again

   If it crashes, the culprit is in the half you moved back. If it does not, it is in the other half. Repeat. Each round halves the candidates, so even thirty plugins take about five restarts.

3. Put the rest back once you have found it

   Restore every jar except the one you identified, and confirm the server is stable before you go looking for a replacement plugin.

Reading a crash report

When the server crashes outright it writes a file into crash-reports/, named with the date and time. A crash report has a description line, a stack trace, and then a long system details section.

What to look for, in order:

• The Caused by: chain. Read to the innermost one. That is the actual failure, and everything above it is a wrapper.
• The first line in the trace that is not Minecraft's own code. Frames beginning net.minecraft, org.bukkit, or io.papermc are the server. A frame with a package like com.example.someplugin names the plugin that was running when it fell over.
• The log line prefix. Paper prefixes messages from a plugin with that plugin's name, so an exception logged as coming from a plugin usually says so before the trace even starts.

Two specific messages worth recognising:

• The server has stopped responding! followed by a thread dump is the watchdog. It means a single tick ran for far longer than it should have. The main thread's stack in that dump shows exactly what it was doing, and that is often the fastest way to identify a plugin that hangs the server.
• OutOfMemoryError is a heap problem, not necessarily a plugin bug. Start with heap sizing in Optimising a Minecraft server, then look for a plugin holding on to memory it should have released.

NoClassDefFoundError, ClassNotFoundException, and NoSuchMethodError almost always mean a version mismatch: a plugin compiled against a different server version, or a missing dependency, rather than a bug in the plugin's logic.

Test on a copy, not on the live server

Anything you would not want to explain to fifty players mid-session belongs on a copy first: a Minecraft version bump, a Paper build change, a big plugin update, or a config change that touches gameplay.

1. Copy the server while it is stopped

   ShellCopy

   sudo systemctl stop minecraft
   sudo -iu minecraft
   cp -a ~/server ~/server-test

   Copy while the server is running and you will capture a region file that was half-written, which is exactly the kind of corruption you were trying to avoid.

2. Move the copy off the public port

   In ~/server-test/server.properties, set server-port to something else, for example 25566, and set server-ip=127.0.0.1 so the test server only listens on the loopback interface and is not publicly reachable at all.

3. Reach it through an SSH tunnel

   From your own machine:

   ShellCopy

   ssh -L 25566:127.0.0.1:25566 you@203.0.113.10

   Leave that session open and connect your Minecraft client to localhost:25566. No extra port rule, and nothing exposed to the internet while you experiment.

4. Actually exercise it

   Start the copy, join it, and use the features you changed. Walk into ungenerated terrain, trigger the plugin, break and place blocks, and watch MSPT with /spark tps while you do. A server that starts without errors has not been tested.

5. Apply the same change to live

   Once it holds up, repeat the exact steps on the real server, during a quiet window, with a fresh backup taken first.

Related