Minecraft plugin problems

This page is for plugin problems on Paper, Spigot, Purpur and similar software. To install plugins, see Minecraft plugins.

Plugin not loading or not showing in /plugins

Why it happens: The server only loads plugins that are valid .jar files in the plugins folder and that start without errors. A plugin that fails to start is not listed as green.

How to fix it:

1. Open Files and go to the plugins folder. Make sure the file ends in .jar and is directly in plugins, not in a subfolder.
2. Restart the server. Plugins load at startup.
3. Read the Console just after start for lines with the plugin name and “Could not load” or an error.
4. Check the plugin’s page for the Minecraft versions and server software it supports.
5. Make sure the file was not uploaded as a .zip. Unzip it if it is a bundle and use the .jar inside.

Plugin is red in the plugin list

Why it happens: In /plugins (or /pl), green means enabled and red means it failed to enable. The Console tells you why.

How to fix it:

1. Scroll up in Console to the start and find the first error mentioning the plugin.
2. Common reasons are listed below: wrong version, missing dependency, bad config.
3. Fix the cause and restart. A red plugin will not fix itself.

Unsupported API version

Unsupported API version 1.21

Why it happens: The plugin says it needs a Minecraft API version that your server does not provide. Either the plugin is newer than your server or it is very old.

How to fix it:

1. Check your server version in the Console startup lines.
2. Download the plugin build made for that version.
3. If the plugin is too new, either update the server (see Change version) or use an older plugin release.
4. If the plugin is old and abandoned, look for an up-to-date alternative.

Wrong Minecraft version for the plugin

Why it happens: Many plugins only work on certain Minecraft versions. One built for 1.16 may break on 1.21.

How to fix it:

1. Look at the plugin’s download page for its supported versions.
2. Use the plugin build that matches your server version.
3. If you changed server versions recently, update all plugins at the same time.

Missing dependency (Vault, ProtocolLib, PlaceholderAPI)

Could not load 'plugins/Example.jar' ... Unknown dependency Vault. Please download and install Vault to run this plugin.

Why it happens: Some plugins need another plugin to run. Common ones are Vault (economy and permissions bridge), ProtocolLib and PlaceholderAPI.

How to fix it:

1. Read the error. It names the missing plugin.
2. Install it from the Plugins page or upload its jar to the plugins folder with Files.
3. Restart the server.
4. Vault also needs an economy or permissions plugin behind it, such as LuckPerms or EssentialsX, to be useful.

Plugin conflict (two plugins doing the same job)

Why it happens: Two plugins that both handle chat, economy, permissions or protection can fight each other and cause errors or odd behaviour.

How to fix it:

1. Note when the problem started and which plugin you added last.
2. Remove the newest plugin (see “How to disable a plugin safely”) and test.
3. Keep one plugin per job.
4. Check the plugin pages for known conflicts.

Plugin config was reset or is being ignored

Why it happens: Some plugins overwrite their config when they update. Also, editing while the server is running can be undone because the plugin saves its own copy when it stops.

How to fix it:

1. Stop the server before editing config files.
2. Edit the file in Files, save, then start the server.
3. If the plugin regenerates the file, the YAML may have a mistake. Look for tabs or wrong spacing.
4. Make a copy of the config before big changes.

Editing a plugin config while the server is running

Why it happens: The plugin holds settings in memory. When it saves or the server stops, it can write its old values over your edit.

How to fix it:

1. Stop the server.
2. Edit and save the config in Files.
3. Start the server again.
4. Some plugins have a reload command such as /pluginname reload. This works for some plugins only. Restarting is safer. Avoid the built-in /reload, because it can leave plugins in a broken state.

Permissions not working

Why it happens: Plugin commands are guarded by permission nodes. Being an operator (/op) gives broad access, but normal players need the right node, and some plugins ignore op.

How to fix it:

1. Install a permissions plugin such as LuckPerms if you do not have one.
2. Find the permission node in the plugin’s docs.
3. Grant it to a player or a group. LuckPerms basics:

   lp user <name> permission set <node> true
   lp group default permission set <node> true

4. Create groups (for example vip) and put players in them:

   lp creategroup vip
   lp user <name> parent add vip

5. Do not make everyone an operator. It gives full server access.
6. Test with a non-op account.

WorldEdit and WorldGuard basics

Why it happens: These plugins need permissions, and WorldGuard regions block building by default until set up.

How to fix it:

1. WorldEdit: select two corners with the wand (//wand), then use commands such as //set stone. Needs worldedit.* permissions.
2. WorldGuard: define a region with /rg define <name> after selecting an area, then use flags with /rg flag <name> <flag> <value>.
3. If a player cannot build, check for a region covering the area and the build flag.
4. WorldEdit needs the matching WorldEdit version for your Minecraft version, and WorldGuard needs the matching WorldEdit.

Unknown command or “I don’t know that command”

Unknown or incomplete command, see below for error

Why it happens: The plugin is not loaded, you typed the command wrong, or you lack permission (some servers hide commands you cannot use).

How to fix it:

1. Run /plugins and check that the plugin is green.
2. Try /help <plugin> or the plugin’s name with a colon, like /essentials:home.
3. Check permissions (see above).
4. Two plugins may register the same command. The prefixed form picks a specific one.

Installed from the Plugins page but not running

Why it happens: Plugins are loaded when the server starts. Adding one to a running server does not start it.

How to fix it:

1. Restart the server from the power bar (Restart).
2. After restart, run /plugins to check it is green.
3. If not, see “Plugin not loading”.

A plugin update broke something

Why it happens: New plugin versions can change config formats, commands or Minecraft version support.

How to fix it:

1. Restore the older jar. Keep the old jar in a backup or download the earlier version.
2. Restore the plugin’s folder from a backup if configs were changed (see Backups).
3. Read the plugin’s changelog before updating next time.
4. Make a backup before every update.

Plugin does not work on Folia

Why it happens: Folia is a special server software that runs regions on many threads. Most plugins are not written for it and will fail.

How to fix it:

1. Check the plugin page for “Folia supported”.
2. If it is not, use a normal Paper server or find a Folia version of the plugin.
3. See Server software.

Paper, Spigot and Bukkit plugin compatibility

Why it happens: Paper is built on Spigot, which is built on Bukkit, so Bukkit and Spigot plugins usually run on Paper. The reverse is not true: a Paper-only plugin will not run on Spigot.

How to fix it:

1. Check the plugin page for the supported software.
2. Prefer plugins that say they support your software.
3. Fabric, Forge and NeoForge use mods, not plugins. See Minecraft mod problems.
4. Vanilla does not run plugins.

Plugin needs a database

Why it happens: Some plugins (permissions, stats, economy, web shops) can store data in MySQL or MariaDB.

How to fix it:

1. Open Databases in the panel and create a New Database. The count is limited by your plan.
2. Copy the endpoint, database name, username and password shown into the plugin’s config.
3. Many plugins also work with a built-in file database (SQLite or H2). If you do not need MySQL, keep that default.
4. Restart the server and check the Console.

Plugin needs an extra port (web map, voice chat)

Why it happens: Web maps (such as Dynmap or BlueMap) and voice chat plugins listen on their own port, separate from the game port. Players can only reach it if that port is allocated to your server.

How to fix it:

1. Open Network and check how many allocations your plan allows.
2. If one is free, use Create Allocation, then set the plugin to use that port in its config, and restart.
3. If players still cannot reach it, or you have no free allocations, open a ticket with the plugin name and we will check.
4. Do not guess the port. The plugin must be told the exact allocated port.

Plugin console errors

Why it happens: Errors with a plugin name show a failing feature, a bad config or an incompatibility.

How to fix it:

1. Find the first error. Later ones are often caused by it.
2. Look for the plugin name in the first lines of the stack trace.
3. Search the exact error text with the plugin name.
4. Update the plugin, fix the config, or remove it.
5. Ask the plugin author with the whole error text if you cannot find an answer.

How to disable a plugin safely

Why it happens: You want to test or remove a plugin without deleting its data.

How to fix it:

1. Stop the server.
2. Open Files, go to the plugins folder.
3. Rename the jar, for example Example.jar to Example.jar.disabled. It will not load.
4. Start the server.
5. To remove it fully, delete the jar. The plugin’s data folder stays until you delete it too. Keep it if you might reinstall.
6. Back up before removing big plugins such as permissions or economy, because other plugins may depend on them.

How to find a plugin’s config folder

Why it happens: Config files are not next to the jar.

How to fix it:

1. Open Files, then the plugins folder.
2. Look for a folder named after the plugin. If you do not see it, the plugin has never started successfully.
3. The main file is often config.yml.

Still stuck?

Open a ticket or ask on Discord. See Contact support. Include the plugin name and version, your server version, and the Console lines with the error.