You installed the plugin pack on your server, restarted with the stop command, opened the console... and your eye landed on red ERROR lines. Either the plugins never load, or they look loaded but do nothing when you type a command, or the server crashes on startup. This page walks through the 15 most common problems you can hit after installing a plugin pack, in detail: the typical log output, the root cause and a step-by-step fix for each one.

Reading logs is the most valuable skill a Minecraft server admin can have. Every line starting with ERROR has a reason, and in 9 cases out of 10 that reason is written right there. Ignoring the log only makes problems bigger; always open logs/latest.log first.

Problem 1: NoClassDefFoundError

text
[ERROR]: Could not load plugin ChestShop.jar
java.lang.NoClassDefFoundError: net/milkbowl/vault/economy/Economy
    at com.Acrobot.ChestShop.ChestShop.onEnable()
    ... (stack trace)

Cause: The plugin is trying to reach a class belonging to another plugin, but that plugin is not there. In the example ChestShop depends on Vault, but Vault has not been loaded.

Fix: Add the missing dependency to the plugins/ folder and do a full server restart. Check each plugin's plugin.yml and look at the depend: field:

bash
# List the dependencies of every plugin at once
for jar in plugins/*.jar; do
  echo "=== $jar ==="
  unzip -p "$jar" plugin.yml | grep -E "^(name|depend|softdepend):"
  echo
done

Problem 2: UnsupportedClassVersionError

text
[ERROR]: has been compiled by a more recent version of the Java Runtime
(class file version 65.0), this version of the Java Runtime only recognizes
class file versions up to 61.0

Cause: The plugin was compiled with a newer Java version than yours. 61.0 = Java 17, 65.0 = Java 21. The plugin was built with Java 21 and you are running Java 17.

Fix: Upgrade your Java version.

bash
# Check the current Java version
java -version

# Installing Java 21 on Ubuntu/Debian
apt update
apt install -y openjdk-21-jre-headless

# Set the default Java
update-alternatives --config java

# Verify
java -version  # should read openjdk 21.x.x

Problem 3: YAML Parse Error (broken config)

text
[ERROR]: Could not load 'plugins/EssentialsX/config.yml'
while parsing a block mapping
  in 'reader', line 45, column 3:
      message: 'Test
      ^
expected <block end>, but found '<scalar>'

Cause: The config file is malformed YAML. Typical reasons: a missing quote, wrong indentation (using tabs), an unclosed string.

Fix: Go to the line named in the error. Use a YAML validator:

bash
# Validate the file locally
python3 -c "import yaml; yaml.safe_load(open('plugins/EssentialsX/config.yml'))"

# Online: https://www.yamllint.com/
# VSCode: the YAML extension underlines errors in red

Problem 4: The Server Will Not Start, Java Throws an Error

text
Error occurred during initialization of VM
Could not reserve enough space for 4194304KB object heap

Cause: The system cannot allocate the RAM the server is asking for. Either the machine does not have enough RAM, or Java is 32-bit.

Fix:

bash
# Check total RAM
free -h

# Check the Java architecture
java -d64 -version  # on 64-bit you see "Running in 64-bit mode"

# Lower the -Xmx value in your startup command
# Example: 2GB instead of 4GB
# -Xms2G -Xmx2G

Problem 5: Port Already in Use

text
[ERROR]: The exception was: java.net.BindException: Address already in use
[ERROR]: Perhaps a server is already running on that port?

Cause: Port 25565 (or whatever you set in server.properties) is held by another process.

Fix:

bash
# Who is holding the port?
sudo lsof -i :25565
sudo netstat -tulpn | grep 25565

# Kill the process
sudo kill -9 <PID>

# Alternative: change the port in server.properties
# server-port=25566

Problem 6: MySQL Connection Error

text
[ERROR] Failed to connect to database
com.mysql.cj.jdbc.exceptions.CommunicationsException:
Communications link failure

Cause: The MySQL/MariaDB service cannot be reached. Wrong host, port or password, or MySQL is down.

Fix checklist:

  • systemctl status mariadb — is the service running?
  • Try connecting from the command line with mysql -u user -p
  • Is the host in the config localhost or 127.0.0.1?
  • For remote MySQL, is bind-address open?
  • Is the firewall blocking port 3306?
  • Has the user been granted privileges? SHOW GRANTS FOR 'user'@'localhost';

Problem 7: The Plugin Looks Loaded but the Commands Do Nothing

text
Typing /home returns: Unknown command. Type "/help" for help.

Cause: The plugin loaded but no permission was granted, or another plugin is claiming the same command.

Fix:

bash
# 1. Check the permission first
/lp user <player> permission check essentials.home

# 2. Is there a command conflict?
/version  # every plugin shows up in the list
/plugin info EssentialsX  # which commands does it provide?

# 3. Is the plugin enabled?
/plugins  # is EssentialsX green?

# 4. Alternative: run the command with the plugin prefix
/essentials:home

Problem 8: The World Will Not Load (World Corruption)

text
[ERROR]: Couldn't load chunk [10, 20]: Region file not found.
[ERROR]: Failed to load world 'world': null

Cause: World files are corrupt or missing. It usually happens after force-killing the server (Ctrl+C, kill -9).

Fix:

  • Restore from a backup if you have one
  • Open the world in MCEdit or Amulet and delete the broken chunk
  • If world/level.dat is corrupt, copy it back from world/level.dat_old
  • Last resort: create a new world and move the critical builds over from the old one with WorldEdit

Problem 9: TPS Is Permanently Low

The console keeps printing Can't keep up! Is the server overloaded?, players complain about lag, TPS sits around 15.

Cause: The server is doing more work than it can handle. Usually: too many entities (mobs, items), too many loaded chunks, a heavy plugin or a disk I/O problem.

Fix: Take a profile with Spark and find the root cause.

text
/spark profiler --timeout 120
# It finishes automatically after 120 seconds and gives you a link
# The link shows which plugin is burning CPU

Problem 10: The Plugin Crashes

text
[SEVERE]: Error occurred while enabling PluginName v1.0.0
java.lang.NullPointerException
    at com.example.plugin.Main.onEnable(Main.java:45)

Cause: A bug in the plugin code. Usually a missing field in the config, a wrong format or an API change.

Fix:

  • Delete the config and restart the server → the plugin regenerates a default config
  • Update the plugin version; it may have been a known bug
  • Go to the developer's GitHub Issues — has anyone else reported it?
  • Your Minecraft version may not be supported

Problem 11: The Menu (GUI) Does Not Open

Nothing is logged to the console, but when a player types /shop nothing happens, or an empty inventory opens.

Cause: Usually the wrong ProtocolLib version or a missing PAPI. Most modern GUI plugins write data into item lore through PAPI placeholders; without PAPI the menu breaks.

Fix:

bash
# Is PlaceholderAPI up to date?
/papi version
# If needed: /papi ecloud download <expansion>
/papi ecloud download Player
/papi ecloud download Vault
/papi reload

# Is ProtocolLib up to date?
/version ProtocolLib
# Latest release: https://www.spigotmc.org/resources/protocollib/

Problem 12: Player Data Keeps Disappearing

Players log out and back in and lose their inventory, homes and balance. Not randomly — consistently.

Cause: An error while saving data, or duplicate player data.

  • Two economy plugins enabled: for example EssentialsXEcon + CMIEcon. Disable one of them
  • MySQL autocommit off: make sure auto-commit: true is set in the config
  • Shifting UUIDs: in offline mode UUIDs are derived from the name; if the name changed, the data is gone
  • World corruption: player data lives in world/playerdata/, and a corrupt file cannot be read

Problem 13: Chat Messages Appear Twice

A player types hello and chat shows hello hello.

Cause: Two chat formatter plugins are running at once. EssentialsXChat + DeluxeChat + CMI chat, for example.

Fix: Keep a single chat plugin and remove the others from the plugins folder.

Problem 14: I Got Kicked / Cannot Connect: Internal Exception

text
Client disconnected: Internal Exception:
io.netty.handler.codec.DecoderException: java.io.IOException:
Payload may not be larger than 1048576 bytes

Cause: The packet size limit was exceeded. Usually ProtocolLib or a disguise plugin is sending an oversized packet.

Fix:

  • Update ProtocolLib
  • Lower compression-threshold in plugins/ProtocolLib/config.yml
  • If the disguise plugin is on an old version, update it
  • Raise max-bytes-per-second in paper-global.yml

Problem 15: The Server Freezes Now and Then, Then Recovers

TPS is a steady 20, but every five minutes the server freezes for 10 seconds. A garbage collection spike.

Cause: Suboptimal JVM GC settings. If you run a large -Xmx value with the default GC, stop-the-world pauses of 10-15 seconds are normal.

Fix: Use Aikar's Flags for tuned G1GC settings:

bash
# Aikar's flags (tuned for Paper)
java -Xms4G -Xmx4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 \
  -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true \
  -jar paper.jar nogui

The Art of Reading Logs

The formula for solving any problem is the same: open the log, find the ERROR or WARN lines, read the stack trace. The log directory looks like this:

text
logs/
├── latest.log          # Log of the currently running server
├── 2026-04-15-1.log.gz # Yesterday's log (compressed)
├── 2026-04-14-1.log.gz
└── ...

Log format:

text
[16:23:45 INFO]: [EssentialsX] Loading EssentialsX v2.20.1
[16:23:45 WARN]: [ChestShop] Could not find Vault, disabling...
[16:23:46 ERROR]: Plugin PluginName generated an exception:
    java.lang.NullPointerException
        at com.example.plugin.Main.onEnable(Main.java:45)

[timestamp] [level]: [plugin] message

INFO: information, can be ignored. WARN: a warning, pay attention. ERROR: an error, it must be fixed. SEVERE / FATAL: critical — the server has crashed or is about to.

Tools That Speed Up Diagnosis

  • Spark: TPS, MSPT, thread profiles, memory
  • mcstatus / mcping: is the server reachable from outside?
  • pastebin log upload: share the log to get help from others
  • Minecraft Server Status Checker: is the port open, is there an SRV record
  • JStack (Java): thread dumps, deadlock detection
  • VisualVM: JVM memory profiling

Troubleshooting Flow Chart

Follow this whenever you hit a problem:

text
1. Is the server down? → Start it
     ↓ (yes, it is running)
2. Open logs/latest.log
     ↓
3. Find the oldest ERROR line
     ↓
4. The first line of the stack trace names the plugin
     ↓
5. Search the error message on Google (e.g. "NoClassDefFoundError Vault")
     ↓
6. Apply the fix, restart the server
     ↓
7. Read the log again — any ERROR left?
     ↓ (yes)   ↓ (no)
  Back to 3    → Problem solved

When Should You Ask for Support?

If you have worked through the 15 problems above and are still stuck, it is time for professional support. Before you open a ticket, gather:

  • Server version (e.g. Paper 1.20.4)
  • Java version (java -version)
  • Operating system (uname -a)
  • RAM/CPU details (free -h, nproc)
  • Plugin list (output of /plugins)
  • The last 100 log lines (tail -n 100 logs/latest.log)
  • A link to a Spark report (if you have one)
  • A clear description of what the problem is

The First Week After Installing a Plugin Pack

The first week after installing a pack is the most critical period. Around 80% of problems surface in that window. Daily checklist:

Daily Tasks (First 7 Days)

  • Morning: open the log, check for new ERRORs
  • Midday: performance check with /tps
  • Evening: collect feedback from players — anything broken?
  • Night: take a backup, check disk usage

Weekly Tasks

  • Detailed performance analysis with the Spark profiler
  • Check for plugin updates (you can automate this by installing a PluginUpdater plugin)
  • MySQL database size and index optimisation
  • Move world backups to another location (S3, another VPS)
  • Review the player ban/mute logs

Professional Log Analysis: Fast Diagnosis with Grep

As log files grow, reading them by hand becomes impossible. On Linux, combinations of grep, awk and tail save hours of work:

bash
# Show every ERROR from the last hour
grep -E "\[.{5} ERROR\]" logs/latest.log

# Find and count the plugin behind each ERROR
grep -E "ERROR" logs/latest.log | grep -oP "\[\w+\]" | sort | uniq -c | sort -rn

# TPS warnings from the last hour
grep "Can't keep up" logs/latest.log

# Every log line about one plugin
grep "EssentialsX" logs/latest.log | tail -100

# Show the first 5 lines of each stack trace
grep -A 5 "Exception" logs/latest.log | head -50

# Search across all gzipped logs too (older logs)
zgrep -h "OutOfMemoryError" logs/*.log.gz logs/latest.log

How to Describe the Problem Properly When Asking for Help

Writing the plugin doesn't work on Discord will not get you an answer. The format of a professional help request:

markdown
# Short summary
After installing EssentialsX my players cannot use /home.

# Environment
- Paper 1.20.4 build 497
- Java 21.0.1
- Ubuntu 22.04, 4 GB RAM
- 38 plugins in total

# The error
When a player types /home:
> Unknown command. Type "/help" for help.

# Log (output of /plugins)
EssentialsX v2.20.1 - GREEN (looks like it is running)

# What I already tried
- /lp user TestUser permission check essentials.home → denied
- essentials.home was added to the default group in LuckPerms
- /lp reload was run

# Expected
The /home command to work

A question in this format gets solved in 10 minutes; a it doesn't work question can go unanswered for days.

Frequently Asked Questions

There is an ERROR in the log but the server seems fine — can I ignore it?

No. Every ERROR means something is going wrong. The server may be running right now, but it is very common for the problem to blow up two weeks later. Find the cause of every ERROR, and write down the fix one by one. That habit is what turns you into an expert server admin.

Several plugins are erroring at once. Which one do I fix first?

Follow the dependency chain. Core plugins such as Vault and ProtocolLib load first, and their errors trigger the rest. Fix the errors in plugins that depend on nothing else first; the plugins above them often fix themselves.

If I delete a plugin completely, does its data stay behind?

Deleting the plugin's jar disables the plugin. But the config, data and YAML files in plugins/PluginName/ remain. The tables it created in the database (MySQL) are not removed either; you have to drop them manually with DROP TABLE. For a full cleanup, delete the jar, the folder and the database tables separately.

I keep getting OutOfMemoryError — do I need more RAM?

Do not add RAM straight away. First check whether there is a memory leak. Take a heap dump with Spark: /spark heapdump. If one plugin's classes occupy 40% of the heap, that plugin is leaking. Update it or replace it with an alternative. Adding RAM only makes sense when there is no leak.

The server shuts down at random — why?

A few possible causes: (1) the OOM killer (Linux kills the process when it runs out of memory), (2) a JVM crash (it writes an hs_err_pid*.log), (3) a process limit (ulimit), (4) the VPS host itself is faulty. dmesg | grep -i kill shows what the Linux memory killer has killed.

Prevention: A Pre-Install Checkpoint

Most errors can be prevented in advance. Clear these checkpoints before installing a plugin pack:

  • Is the Java version correct? (java -version)
  • Is the server software Paper, and is it up to date?
  • Is there enough RAM? (4 GB required, 4 GB available)
  • Is there enough disk space? (20 GB+ free)
  • Are the network ports open? (25565 TCP)
  • Is MySQL/MariaDB running? (systemctl status)
  • Was a backup taken in the last 24 hours?
  • Has the pack been tried on a test server first?

Skipping these checkpoints and installing anyway invites 60% of all errors.

Emergency Response Plan

As the server grows you need an emergency plan prepared in advance for the unexpected. So that you can make cool-headed decisions when the server goes down at 3 AM:

Level 1: Minor — low TPS, a plugin error

  • Check /tps and /mem
  • Take a quick Spark profile (60 seconds)
  • Identify the heavy plugin, change its config
  • Fix the server in 5-10 minutes

Level 2: Moderate — server crash, a plugin not working

  • Read the log, list the ERRORs
  • Start the server in safe mode (minimum plugins)
  • Isolate the plugin causing the problem
  • Restore the plugin config from a backup
  • Fix within 30-60 minutes

Level 3: Severe — disk corruption, OutOfMemory, world loss

  • Stop the server (before losing more data)
  • Notify players (via Discord)
  • Full restore from backup
  • Check disk health (smartctl)
  • Add RAM or migrate the server
  • Downtime of 2-24 hours

Level 4: Disaster — DDoS, a breach, mass data loss

  • Urgent notice: Discord, players
  • Shut the server down, protect the IP
  • Forensics: who attacked, and how did they get in?
  • Recover from the last clean backup
  • Security hardening
  • Migrate to a new server if necessary

Monitoring: Catching Errors Proactively

Finding out when the server already has a problem is too late. Real professionals know before there is a problem. Monitoring systems you can set up:

  • Prometheus + Grafana: TPS, MSPT, RAM, CPU and player-count metrics on a dashboard
  • Discord webhook: push every ERROR to a Discord channel automatically
  • PagerDuty / Opsgenie: SMS to your phone on a critical alert
  • UptimeRobot: is your server online? checked every 5 minutes
  • Loki + Promtail: centralised log management and search
  • Sentry: exception tracking and deduplication

The most important skill in the face of server problems is patience. Every problem gets solved; panicking and wiping the server does more damage in the long run. Learning to read logs, searching the error message on Google, asking the community for help — these are the skills of professional server administration.