How to use this library
Match the exact message first. Then identify whether the failure happens before the server starts, while the client connects, or after a player joins. Save the relevant log lines before restarting, because a restart can remove the evidence you need.
| Message or symptom | What it usually means | First checks |
|---|---|---|
| Connection refused | The address resolved, but no service accepted the connection. Confirm the server is online, the correct port is listening, and the firewall allows the right protocol. | Start with console logs, server status, software version, address, and the most recent change. |
| Connection timed out | The client waited without receiving a useful response. Test the route, firewall, public address, port forwarding, and whether the hosting node is reachable. | Start with console logs, server status, software version, address, and the most recent change. |
| Failed to verify username | Java authentication could not verify the account. Check official service availability, online-mode settings, system time, and whether a proxy is forwarding identity correctly. | Start with console logs, server status, software version, address, and the most recent change. |
| Incompatible client | The client and server do not support the same game or protocol version. Match the exact release or install a deliberately configured compatibility layer. | Start with console logs, server status, software version, address, and the most recent change. |
| Missing mods / mismatched mod list | A modded client and server disagree about required files or versions. Compare manifests, loaders, dependencies, and configuration files. | Start with console logs, server status, software version, address, and the most recent change. |
| OutOfMemoryError | The Java process could not allocate required memory. Review heap limits, total container memory, world/plugin/mod growth, and whether a leak or runaway task is present. | Start with console logs, server status, software version, address, and the most recent change. |
| Watchdog / single server tick took too long | A tick exceeded the watchdog threshold. Inspect the preceding stack trace, recent plugins/mods, chunk generation, entity farms, and storage stalls. | Start with console logs, server status, software version, address, and the most recent change. |
| Address already in use | Another process is already bound to the requested port. Stop the duplicate process or configure a different assigned port. | Start with console logs, server status, software version, address, and the most recent change. |
| Unable to access jarfile | The startup command references a JAR name or path that does not exist. Match capitalization and the actual uploaded filename. | Start with console logs, server status, software version, address, and the most recent change. |
| Unsupported class file major version | The JAR was built for a newer Java runtime. Install the required Java version or use software compiled for the installed runtime. | Start with console logs, server status, software version, address, and the most recent change. |
| Invalid or corrupt jarfile | The JAR is incomplete, HTML was downloaded instead of the file, or storage corrupted it. Re-download from the official project and verify the file size. | Start with console logs, server status, software version, address, and the most recent change. |
| You are not whitelisted | The server is private and the account is not allowed. Add the exact player name or UUID using the server’s supported allowlist command. | Start with console logs, server status, software version, address, and the most recent change. |
| Disconnected: server closed | The server stopped, restarted, crashed, or was intentionally shut down. Read the final console lines and panel event history. | Start with console logs, server status, software version, address, and the most recent change. |
A reliable troubleshooting order
- Copy the exact error and timestamp.
- Check whether the server is online and listening.
- Confirm edition, software, and version.
- Review the last configuration, plugin, mod, or world change.
- Test with one known-good client.
- Restore only after saving logs and the current broken state.
When to contact support
Include the server software, game version, panel status, exact address format, the first error in the console, and what changed immediately before the issue. Remove passwords, API keys, session tokens, and private player data.
Startup errors versus connection errors
If the server never reaches a ready state, focus on Java, JAR paths, software versions, mods, plugins, configuration, memory, and file permissions. If the server is ready but players cannot join, focus on edition, address, port, protocol, authentication, DNS, firewalls, and client version. Mixing these layers wastes time.
What a good error report looks like
Example: “Paper server, Minecraft [version], Java [version]. Status changed to Offline at 14:32 UTC after installing [plugin and version]. The first console error is [exact line]. Restoring the previous plugin file returns the server to Online.”
This format gives support a reproducible timeline and a likely change boundary without exposing private credentials.