A plugin that will not load: what Paper says, and what it wants from you

Start with the plugins command

Type plugins in the Console tab, or /plugins in the game as an operator; pl does the same. The answer starts with Server Plugins and the total, then splits the names into Paper plugins and Bukkit plugins. In the game each name has a colour, and that colour is your first clue. The panel console strips server colours, so there you go by name.

Initializing plugins...
Initialized 2 plugins
Bukkit plugins (2):
 - LuckPerms (5.5.71), Vault (2.20.2)

This startup summary is the most useful list you have. A plugin named here was read correctly and failed later, so search for its name further down. A plugin missing from it was skipped before Paper learned its name, which points at the file itself. Clicking a name in the game runs /version for that plugin and shows which release is really running.

The line that names the reason

On the Console tab, set the level menu to Errors and look for lines starting with Could not load or Error occurred while enabling. The reason sits on the lines under it, which lack the word ERROR, so that filter hides them. Once you have the plugin name, go back to All levels and type the name into Search logs... instead. The whole run is in logs/latest.log, and the guide to logs and crash reports shows how to follow a stack trace.

One line looks alarming and is harmless: The spark plugin will not be loaded as this server bundles the spark profiler. Paper already contains spark, so the extra jar is skipped and the spark commands still work.

Unknown dependency, soft dependencies and load order

Could not load 'plugins/<file>.jar' in 'plugins'
org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault].
Please download and install these plugins to run '<plugin>'.

Every plugin carries a short description of itself, including the other plugins it relies on. Paper knows three kinds of relation, and only one can stop a plugin from loading:

The names in the brackets are plugin names, not file names, and must match exactly. That matters for Vault: its last release dates from July 2020. VaultUnlocked is still updated for 26.2 and calls itself Vault in its description, so it satisfies plugins that ask for Vault. VaultUnlocked and LuckPerms are both in the plugin catalog on the Plugins tab. Paper lists every missing hard dependency of a plugin in that one line, so install them all before you restart. The economy guide explains what Vault is for.

Paper plugins declare this differently

Newer plugins may use paper-plugin.yml instead. They list dependencies separately for the early bootstrap stage and for the running server, each marked required or not and loading BEFORE or AFTER, or with the order left out as OMIT. Unlike Bukkit plugins, they get no help when two plugins wait on each other. They appear under Paper Plugins in the list, and Paper warns that they do not support a reload, so restart instead.

Unsupported API version, or a Java that is too old

Could not load plugin '<file>.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: Unsupported API version 26.2

The api-version in plugin.yml names the Minecraft version the plugin was built against, and a server older than that refuses it. The number in the error is the plugin's: marked 26.2, it will not load on 26.1.2, and marked 1.21.4, it will not load on 1.21.1, because from 1.20.5 on the last part of the number counts too.

• Take a release made for your version. In the plugin catalog, the Version list on each card only holds releases matched to the server type and version shown beside the catalog title.
• Or move the server up to the version the plugin wants, if your other plugins exist there as well.

A plugin without any api-version still loads, with Legacy plugin ... does not specify an api-version. as a warning and a yellow star in the list. Paper describes those as made on very old, unsupported versions of the game.

The same Could not load plugin line can also be followed by a class file version error. That is about Java, not Minecraft: the plugin was compiled for a newer Java than your server runs. The Java version guide turns both numbers into Java versions and explains how our panel picks the runtime.

Files that were never a plugin for this server

Paper only considers files ending in .jar that sit directly in the plugins folder, and inside each one it looks for paper-plugin.yml or plugin.yml. Anything else is ignored without a word or rejected with one line.

Many projects publish one download per platform, and the file name tells them apart. LuckPerms has LuckPerms-Bukkit, LuckPerms-Velocity and LuckPerms-Bungee jars for one release, plus Fabric, Forge and NeoForge files. Paper and Purpur need the Bukkit one; the Velocity file belongs on the proxy of a network.

An archive in plugins gets an Extract button on the Files tab. Afterwards, open any folder it created: a jar in there is still one level too deep. The simplest route is to unpack on your own computer and upload only the jar, then delete the archive.

Two copies of the same plugin

Ambiguous plugin name 'LuckPerms' for files 'plugins/LuckPerms-Bukkit-5.5.71.jar' and 'plugins/LuckPerms-Bukkit-5.5.53.jar' in 'plugins'

Uploading a new version next to the old one, instead of over it, leaves two jars claiming the same plugin name. Paper keeps one and does not check which is newer, so an old release can keep running while you believe the update worked.

1. 1

   Remove the older jar

   Installed on this server on the Plugins tab lists every jar with its size; above twenty plugins, Filter by file name helps. Use Remove on the old file, and if the dialog offers to delete its settings folder, leave that unticked: the newer jar uses the same folder.

2. 2

   Look inside plugins/update

   If a folder named update exists in plugins, a jar in it replaces the plugin of the same name at the next start and then leaves that folder. A forgotten old copy there quietly undoes your update.

3. 3

   Restart and confirm

   Restart and run version with the plugin name to see which release is running.

Loaded, then failed to enable

Enabling <plugin> v<version>
Error occurred while enabling <plugin> v<version> (Is it up to date?)

Here the jar was fine and the plugin began its own setup, which then failed. The Caused by: lines beneath usually lead into that plugin rather than into Paper. Paper's own question in brackets points at the first thing to check: a release made for another server version.

Cannot load plugins/<plugin>/config.yml
mapping values are not allowed here
found character ... that cannot start any token. (Do not use ... for indentation)

The first message often means a value containing a colon without quotes around it. The second is a tab, which YAML refuses for indentation. Both come with a line and column number: open the file with Edit on the Files tab, go to that line and indent with spaces only.

When a file is beyond saving, Rename it to something like config.yml.broken and restart. If the plugin creates its default settings on start, it writes a fresh file, and you copy your own values back from the renamed one.

A routine for finding the culprit

When no line names a plugin, for instance when two plugins fight over one command, narrow it down on purpose. Paper skips files that do not end in .jar, so renaming switches a plugin off without deleting anything.

1. 1

   Write down the current state

   Restart once and copy the startup summary and the output of plugins. That is what you restore at the end.

2. 2

   Keep the libraries on

   Plugins that others depend on, such as VaultUnlocked or a permissions plugin, stay active. Parking them only adds unknown dependency lines and muddies the test.

3. 3

   Park half of the rest

   On the Files tab, open plugins and use Rename to add .off to half of the other jars, so Example.jar becomes Example.jar.off. Restart the server rather than reloading.

4. 4

   Split again

   Problem gone? It is in the parked half, so switch half of those back on. Still there? Park half of the active ones. Thirty plugins take about five rounds.

5. 5

   Restore the names

   Remove .off from every renamed file, restart, and compare plugins with your first list.

If the server itself stops starting along the way, that is a different problem, covered in the startup guide. For picking the server software to begin with, see Paper, Purpur and Spigot compared.