Adding plugins to a Paper server

Before you download anything

Two things have to match, or the plugin will not load and the server log will say so:

• The Minecraft version. A plugin built for 1.21 usually will not load on 26.2. Plugin pages list the versions they support; believe the list, not the comments.
• The server software. Paper runs Bukkit and Spigot plugins, which covers most of what you will find. It does not run Fabric or NeoForge mods. If a download page only offers a .jar for Fabric, it is a mod and it will not work here.

Download from a source that shows the file’s version and upload history. Modrinth and Hangar are the usual two. Avoid reuploads on file lockers: you cannot tell what is in them, and a plugin runs with full access to your server.

1. Upload the file

1. Stop the server from the panel. A plugin dropped in while the server is running is not picked up, and a plugin removed while it is running can leave the server in a confused state.
2. Open the file manager and go to the plugins folder. If it is not there, start the server once and stop it again; Paper creates it on first run.
3. Upload the .jar. One file per plugin. Do not unzip it.
4. Start the server.

2. Check it actually loaded

Watch the console as the server starts. A plugin that loaded prints its name and version, usually as [PluginName] Enabling PluginName v1.2.3. A plugin that did not will print a reason, and the reason is almost always one of these:

• Unsupported API version or requires a newer version of the server. Version mismatch; get the right build.
• Could not load 'plugins/x.jar' ... UnknownDependencyException. It needs another plugin first. Install the dependency, then restart.
• Nothing at all. The file is not a plugin, or it is a client mod.

Type plugins in the console to list what is loaded. Green means enabled.

3. Configure it

Most plugins create a folder under plugins/<name>/ with a config.yml on their first successful start. Edit it in the file manager and restart. YAML is whitespace-sensitive: use spaces, never tabs, and keep the existing indentation.

Restart, do not reload

/reload and /reload confirm look convenient and cause a large share of the strangest bugs people ask us about. It leaves old copies of plugin code running against new copies of the world, and the symptoms show up hours later as duplicated items or corrupted chunks. Stop and start the server instead. On a small server that is about fifteen seconds.

When a plugin breaks the server

If the server will not start after you add one:

1. Read the last 40 lines of the console. The stack trace names the plugin.
2. Rename that plugin’s .jar to .jar.disabled in the file manager, or delete it.
3. Start the server again.

If you cannot tell which one, move half of them out of plugins into a new folder, start, and repeat on whichever half fails. Four or five restarts finds it in a list of twenty.

Take a backup before adding a plugin that touches world data, such as a world editor or an anti-cheat that rewrites chunks. Backups are one click and the one click you will be glad of.

Memory

Plugins are not free. A dozen small ones is fine on 4 GB. A permissions plugin, a world editor, a protection plugin and a map renderer together want more headroom than a vanilla server, and a map renderer in particular will use everything you give it while it works. If the console starts showing long garbage collection pauses, see diagnosing lag before adding anything else, and move up a size from your account if the numbers say so.