Minecraft Plugin Troubleshooting Guide

Minecraft plugins can fail to load, stop working after an update, conflict with other plugins, or produce errors in the server console.

This guide explains how to troubleshoot common plugin problems on a Down Side Hosting Minecraft Java server.

Make sure you know:

• Your Minecraft version
• Your server software, such as Paper, Purpur, or Spigot
• The plugin name
• The plugin version
• Any required dependencies
• Whether the problem started after a plugin, server, or Minecraft update

If you recently installed or updated the plugin, see:

How to Install Plugins on a Down Side Hosting Minecraft Server

How to Update Plugins on a Down Side Hosting Minecraft Server

The server console is one of the most useful places to start troubleshooting.

Open the Console section of your Down Side Hosting server panel.

Restart the server and watch the startup messages.

Look for:

ERROR
WARN
Exception
Could not load
Failed to load
Unknown dependency
Unsupported API

Also search for the plugin's name.

For example:

[ExamplePlugin]

The console may tell you exactly why the plugin failed.

On many Paper, Purpur, and Spigot servers, you can use:

/plugins

or:

/pl

to view the loaded plugins.

You may also be able to run the command from the server console.

If the plugin does not appear, or appears disabled, check the startup console for errors.

Check that the plugin JAR is actually located in:

plugins/

For example:

plugins/
    ExamplePlugin.jar

Make sure you did not accidentally place it in:

plugins/ExamplePlugin/

The .jar file belongs directly inside the plugins folder.

Common causes include:

• Unsupported Minecraft version
• Unsupported Paper, Purpur, or Spigot version
• Missing dependency
• Incorrect Java version
• Corrupted plugin file
• Outdated plugin
• Plugin conflict
• Invalid configuration
• Plugin no longer maintained

Check the plugin's official documentation and download page for compatibility information.

Some plugins require another plugin or library before they can load.

The console may show an error similar to:

Unknown dependency

or:

Missing dependency

Common dependencies can include:

Vault
ProtocolLib
PlaceholderAPI
LuckPerms

The exact requirements depend on the plugin.

Install the required dependency into:

plugins/

Then restart the server and check the console again.

Some plugins list another plugin as a soft dependency.

A soft dependency is usually optional, but certain features may not work without it.

For example, a plugin might run without Vault but disable economy integration.

Check the plugin documentation to determine whether the missing dependency is required or optional.

You may see an error involving:

Unsupported API version

This can happen when a plugin was built for a different Minecraft server version.

Check:

• Your Minecraft version
• The plugin version
• The plugin's supported versions

Install a release of the plugin that supports your server.

Some plugins require a specific minimum Java version.

You may see errors mentioning:

UnsupportedClassVersionError

This commonly indicates that the plugin was compiled using a newer Java version than the server is currently using.

Check the plugin's requirements and your Minecraft server's Java version.

Do not change Java versions without also verifying that your Minecraft server software supports the new Java version.

If the plugin stopped working after updating Minecraft, Paper, Purpur, or Spigot, the plugin may not yet support the newer version.

Check the plugin developer's page for:

• A compatible update
• Development builds
• Known issues
• Migration instructions

If no compatible version exists, you may need to wait for an update or temporarily use an older supported Minecraft server version.

If the problem started immediately after updating the plugin, check:

• Release notes
• New dependencies
• Configuration changes
• Database changes
• Minecraft version requirements
• Java requirements

If necessary, restore the backup created before the update.

See:

How to Update Plugins on a Down Side Hosting Minecraft Server

If the plugin loads but its commands do not work, check:

• Command spelling
• Required permissions
• Operator status
• Plugin configuration
• Plugin documentation
• Command conflicts with another plugin

A player may see:

You do not have permission to use this command.

That usually means the plugin loaded, but the player's permission setup does not allow the command.

If Minecraft displays:

Unknown command

check whether:

• The plugin actually loaded
• The command name is correct
• The command changed in a newer plugin version
• Another plugin overrides the command
• The plugin's command feature is disabled

Check the plugin documentation for the current command syntax.

Many plugins store configuration files in:

plugins/PLUGIN-NAME/

For example:

plugins/ExamplePlugin/config.yml

If you recently edited a configuration file and the plugin stopped working, restore the previous version or check the file for syntax problems.

Many Minecraft plugins use YAML files.

For example:

settings:
  enabled: true
  message: "Welcome"

YAML is sensitive to indentation.

Common problems include:

• Incorrect spacing
• Tabs instead of spaces
• Missing quotation marks where required
• Invalid characters
• Duplicate configuration keys
• Incorrect nesting

The server console may show the line number where the YAML problem occurred.

If you suspect the configuration is broken:

1. Stop the server.
2. Back up the plugin's existing folder.
3. Rename the plugin folder.

For example:

ExamplePlugin

to:

ExamplePlugin-backup

1. Start the server.

If the plugin successfully creates a fresh configuration and loads, the problem may be in the old configuration.

Do not delete the old data until you know whether it contains important player or server information.

Two plugins may attempt to control the same feature or interact in an incompatible way.

Possible signs include:

• Commands behaving incorrectly
• Events firing twice
• Permissions not applying correctly
• Console exceptions
• Features working only when another plugin is removed

If you suspect a conflict, test plugins in smaller groups.

For servers with many plugins, you can temporarily test without some plugins.

Always make a backup first.

One troubleshooting method is:

1. Stop the server.
2. Move several suspect plugin JARs out of the plugins folder.
3. Start the server.
4. Test the problem.
5. Add plugins back gradually until the problem returns.

Do not remove plugin data folders unless necessary.

Moving only the JAR is usually enough for testing.

If you have many plugins and do not know which one is causing the issue, you can speed up testing by removing roughly half of the suspect plugins at a time.

For example, if you have 20 plugins:

1. Back up the server.
2. Remove 10 plugin JARs.
3. Start and test.
4. Determine which half contains the problem.
5. Repeat with that group.

This can identify a problem plugin faster than testing every plugin one at a time.

If the server starts normally but crashes or produces errors when a player joins, check plugins that handle:

• Permissions
• Player data
• Scoreboards
• Tab lists
• Chat
• Join messages
• Inventories
• Authentication
• World management

Look at the console immediately before the crash or disconnect.

The stack trace may identify the plugin involved.

A plugin can load successfully but still cause poor server performance.

Possible signs include:

• Low TPS
• Long tick warnings
• Commands taking a long time
• Delayed block interactions
• Mobs freezing or moving slowly
• Console warnings about the server falling behind

Do not assume low performance is caused by insufficient RAM.

See:

How Much RAM Does a Minecraft Java Server Need?

Plugin workload, CPU performance, world activity, entities, and server configuration can also affect performance.

If memory usage continues increasing over time, a plugin may be storing excessive data or have a memory-related problem.

Before assuming the plugin is responsible:

• Check the server's normal memory usage
• Review recent plugin changes
• Test without the suspected plugin
• Check the plugin's issue tracker
• Make sure you are using a supported plugin version

Restarting the server may temporarily reduce memory usage but does not solve an underlying plugin issue.

Some plugins use:

• SQLite
• MySQL
• MariaDB
• External databases

Database-related errors may include:

Connection refused
Access denied
Database locked
SQL exception

Check:

• Database hostname
• Port
• Username
• Password
• Database name
• Network accessibility
• Whether the database server is running

Do not post database passwords publicly when asking for support.

If the plugin JAR was interrupted during upload or downloaded incorrectly, it may fail to load.

Download a fresh copy from the official plugin source and upload it again.

Make sure the file is a real plugin JAR and not:

• An HTML download page
• A ZIP containing the plugin
• Source code
• An installer intended for another platform

Avoid relying on:

/reload

to install, update, or troubleshoot plugins.

Reloading can leave plugins or server state in an inconsistent condition.

For normal plugin installation and updates, use a full server restart.

Do not troubleshoot based only on the first line of an error.

A Java stack trace may contain several lines showing:

• Which plugin generated the error
• Which class failed
• Which dependency was missing
• Which configuration caused the problem

When asking for support, include the relevant complete error rather than only:

Plugin doesn't work

Collect:

• Minecraft version
• Paper, Purpur, or Spigot version
• Plugin name and version
• Full relevant console error
• When the problem started
• Whether the plugin previously worked
• Recent changes made to the server
• List of relevant dependencies

This information makes troubleshooting much faster.

On server software that displays disabled plugins differently in the plugin list, this generally means the plugin was detected but failed to enable.

Check the server console for the reason.

The plugin may use Vault for permissions, chat, or economy integration.

Install a compatible version of Vault if the plugin lists it as a required dependency.

Also check whether another permissions or economy plugin is required for the feature you are trying to use.

Yes.

A badly broken or incompatible plugin can sometimes prevent normal startup or cause serious runtime errors.

If the server stopped working after adding a plugin, remove the new plugin JAR temporarily and test again.

Usually not as the first troubleshooting step.

Plugin folders may contain important:

• Player data
• Configuration
• Databases
• Permissions
• Economy information

Back up the folder before removing or regenerating it.

Usually not.

Most plugin problems can be isolated by checking the console, plugin compatibility, dependencies, configuration, and recent changes.

Reinstalling the entire server can make recovery harder if you have not backed up your files.

Down Side Hosting supports Minecraft Java plugin servers including Paper, Purpur, and Spigot.

If you need assistance, provide the Minecraft version, server software, plugin name, plugin version, and relevant console error.

Contact Down Side Hosting Support

Down Side Hosting Minecraft Java hosting provides server panel access, file management, console controls, backups, and support for plugin-based server configurations.

Minecraft Java hosting starts at $2/month.

View Minecraft Java Server Hosting

← Back to Minecraft Java Server Guides