When Minecraft fails with UnsupportedClassVersionError, find which component needs newer Java and which executable actually launched it. Installing another JDK does not guarantee that a service, startup script or container will use it.
This guide covers an existing Paper server on Ubuntu 24.04 x86_64 with SSH and sudo. Examples use minecraft.service, the minecraft account and /srv/minecraft from the installation guide. Substitute your own names. Fabric, Forge and NeoForge packs have their own runtime requirements; this Paper version table is not a modpack compatibility promise.
Read the failing component before installing anything#
Save the complete error and the lines before it. On the VPS:
sudo journalctl -u minecraft --since '30 minutes ago' --no-pager
sudo systemctl status minecraft --no-pager -l
sudo systemctl show minecraft -p Result -p NRestarts
The Java exception reference describes an unsupported class-file version. The error often includes the version the class was compiled for and the versions the current runtime recognizes. Keep those numbers in your notes rather than copying an unrelated fix from an older release.
Identify the class or component named in the stack trace. A server launcher failing before world startup points toward the server/runtime pair. A plugin failing during plugin loading may require a different plugin build even when Paper itself runs. If several errors appear, investigate the first relevant failure before secondary exceptions.
| Observation | Next check | Decision |
|---|---|---|
| Server JAR fails before startup completes | Exact downloaded Paper release and its Java requirement | Match the runtime to that release |
| Paper starts but a named plugin fails | Plugin's supported Paper and Java versions | Install a compatible plugin build or test an upgrade on a copy |
Unable to access jarfile | Working directory, filename and permissions | Fix the file path; a Java upgrade does not address this error |
OutOfMemoryError or process disappears | Application and kernel logs | Follow memory diagnosis |
Choose Java for the release you intend to keep#
Paper's current requirements, checked on October 12, 2026, recommend Java 21 for Paper 1.20–1.21.11 and Java 25 for 26.1+. For a 26.1+ installation, use Java 25. Older branches and plugins may impose different constraints; confirm the exact branch before changing anything.
Do not upgrade the game merely to make the error disappear. Players and plugins need to support the resulting release, and a converted world may not safely downgrade. Keep a backup from before any game upgrade. Changing only the runtime for an unchanged JAR avoids introducing a world conversion into this diagnosis.
Find the executable used by the service#
Compare your SSH shell with the unit:
command -v java
java -version
sudo systemctl cat minecraft
sudo systemctl show minecraft -p User -p WorkingDirectory -p ExecStart -p MainPID
Read both the main unit and its drop-ins. If ExecStart runs a shell script, inspect that script too: it may name an older Java path or start a second script. JAVA_HOME is relevant when the launcher uses it; setting it in your SSH shell does not alter an already-running system service. See the systemd service specification.
For the guide's unit, Java is the main process. While it is running, check its executable:
MC_PID="$(systemctl show minecraft -p MainPID --value)"
if [ "$MC_PID" -gt 0 ]; then
sudo readlink -f "/proc/$MC_PID/exe"
sudo ps -p "$MC_PID" -o pid,user,args
fi
If the main process is a wrapper, that path identifies the wrapper, not Java. Use systemctl status to locate the Java process in the unit's process tree and inspect that PID. A process that has already exited cannot provide this evidence; use the configured path and startup log instead. Redact secrets in arguments before sharing them.
A container has its own filesystem and runtime. Installing Java on the Ubuntu host will not update Java inside it. Change the image or launcher configuration through the system that owns that server, preserving its existing data volumes.
Install the selected runtime if it is missing#
Reuse a compatible installed JDK when available. For Paper 26.1+ without Java 25, the Corretto Debian installation instructions provide a signed apt repository. If the repository and keyring already exist, verify them and skip their creation. Do not overwrite unrelated repository files.
sudo apt update
sudo apt install -y ca-certificates curl gnupg
curl -fsSLo /tmp/corretto.key https://apt.corretto.aws/corretto.key
sudo gpg --dearmor -o /usr/share/keyrings/corretto-keyring.gpg /tmp/corretto.key
echo 'deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main' | sudo tee /etc/apt/sources.list.d/corretto.list
sudo apt update
sudo apt install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1
For a selected Paper 1.20–1.21.11 branch, use the verified Corretto 21 package, java-21-amazon-corretto-jdk, instead of the Java 25 package. The libraries follow Paper's Linux Java guide.
Discover the installed Java 25 path; replace the package name with the Java 21 package if that is your choice:
dpkg -L java-25-amazon-corretto-jdk | grep '/bin/java$'
Run that absolute executable with -version, including as the service account. Replace the placeholder in both commands:
MC_JAVA='/ABSOLUTE/PATH/TO/java'
"$MC_JAVA" -version
sudo -u minecraft "$MC_JAVA" -version
The command must report the intended runtime and be executable by minecraft. Select it for this service explicitly. Changing global Java alternatives can affect other Java applications and still leave a hardcoded launcher unchanged.
Change one service and verify the next startup#
Record the current unit and drop-ins so you can restore the exact previous launch command. For the direct-Java unit in our installation guide, run sudo systemctl edit minecraft and add this drop-in. Replace /ABSOLUTE/PATH/TO/java with the path you just verified:
[Service]
ExecStart=
ExecStart=/ABSOLUTE/PATH/TO/java -Xms1G -Xmx2G -jar paper.jar --nogui
The empty assignment clears the previous ExecStart. The second line keeps the installation guide's existing heap and JAR arguments. For another server, retain its actual arguments and working directory; do not replace a custom wrapper with this example without understanding what it does.
During a maintenance window:
sudo systemctl daemon-reload
sudo systemctl restart minecraft
sudo systemctl show minecraft -p ExecStart -p MainPID -p Result
sudo journalctl -u minecraft --since '5 minutes ago' --no-pager
Check the new PID's executable again. Confirm that the log reaches Done, that the previously failing plugins load, and that a matching game client can join. An active service or successful java -version alone proves neither readiness nor plugin compatibility. If the restart fails, preserve the new error before changing another setting.
For ongoing administration, Nexardo's monitoring for supported servers on your own VPS can help retain operational context. VPS enrollment and panel server setup are separate from this manually created service.
If the new runtime introduces a different failure, restore the recorded launch command and reload the unit. Returning to an older game JAR also requires its compatible pre-upgrade world and plugin copies; do not pair it with an already-converted world. Keep the failed and repaired startup logs together with the exact Paper build, plugin build and executable path so the next update starts from a known configuration.
