How to Accept Other Minecraft Versions with ViaVersion
Let newer or older Minecraft clients join your Paper server with ViaVersion, ViaBackwards and ViaRewind: installation, limitations and troubleshooting.
On this page
Your values
Enter them once and the commands in this guide update.
By default, a Minecraft server only accepts clients running its own version. ViaVersion and its add-ons translate the traffic between the client and the server, so that players on another version can connect.
This guide follows on from Install and Update Plugins on Paper. It reuses the /opt/minecraft/server folder, the minecraft.service service and the mc-console command.
By the end of this guide, you will know:
- which plugins to install depending on the versions you want to accept
- how to install and update them with an integrity check
- how to restrict the allowed versions and roll back
Prerequisites
- A Paper server with
mc-console, set up with the Paper guide, along withcurlandjq - SSH access with a user that has
sudoprivileges - A Minecraft client on another version, for the final test
Choose the Plugins
The plugin to install depends on how the client's version compares with the server's:
| Players to accept | Required plugins |
|---|---|
| Client newer than the server | ViaVersion |
| Older client, down to 1.9 | ViaVersion + ViaBackwards |
| 1.7 or 1.8 client | ViaVersion + ViaBackwards + ViaRewind |
Understand the Limitations
ViaVersion translates the protocol, but the game remains the server's. Before opening up to other versions, keep these points in mind:
- Recent content: an older client does not know the new blocks, items and mobs. They are shown to it in an approximate form
- World height: a client older than 1.17 cannot see or touch blocks below
y=0and abovey=255 - Inventories: a client older than 1.17 may experience desyncs on some clicks
- Smithing table: it cannot be used by clients older than 1.19.4 on a 1.20 or newer server, unless you add an add-on module
- Sounds: some recent sounds have no equivalent on older clients
- Anti-cheat: differences in behavior between versions can trigger false alerts. Test your setup
- New versions: ViaVersion is generally released a few days after a Minecraft update
- Bedrock: ViaVersion only concerns Java. For consoles and mobile devices, use Geyser and Floodgate
Back Up the Plugins
ViaVersion does not modify the world, but a backup of the plugins lets you quickly return to the current state:
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins
sudo ls -lh /opt/minecraft/backupsInstall the Plugins
Create a script that downloads the plugins from Hangar, checks that they support your Paper version and verifies their checksums:
sudo nano /opt/minecraft/via-get.sh#!/bin/bash
# Downloads Via plugins from Hangar and verifies their checksums
set -euo pipefail
CIBLE="${1:?Specify the destination folder}"
MC_VERSION="${2:?Specify the server version, for example 26.3}"
shift 2
if [ "$#" -eq 0 ]; then
echo "Specify at least one plugin, for example ViaVersion." >&2
exit 1
fi
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
mkdir -p "$CIBLE"
cd "$CIBLE"
for PLUGIN in "$@"; do
API="https://hangar.papermc.io/api/v1/projects/$PLUGIN/versions?limit=1&channel=Release&platform=PAPER"
VERSION=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c '.result[0]')
if ! echo "$VERSION" | jq -e --arg mc "$MC_VERSION" '.platformDependencies.PAPER | index($mc)' > /dev/null; then
echo "$PLUGIN does not declare support for Paper $MC_VERSION." >&2
exit 1
fi
NOM=$(echo "$VERSION" | jq -r '.downloads.PAPER.fileInfo.name')
URL=$(echo "$VERSION" | jq -r '.downloads.PAPER.downloadUrl')
SHA256=$(echo "$VERSION" | jq -r '.downloads.PAPER.fileInfo.sha256Hash')
curl -fL -H "User-Agent: $UA" -o "$NOM.new" "$URL"
echo "$SHA256 $NOM.new" | sha256sum -c -
mv "$NOM.new" "$NOM"
echo "$NOM is in place."
doneReplace your-domain.com on the UA line, then make the script executable:
sudo chmod 755 /opt/minecraft/via-get.shInstall the plugins you chose. Here is the most common case, to welcome older clients:
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/server/plugins 26.3 ViaVersion ViaBackwardsAdd ViaRewind at the end of the command for 1.7 and 1.8 clients. Specify only ViaVersion if you just want to accept clients newer than the server.
Restart the server and wait for the Done line:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fVerify the Result
sudo mc-console plugins
sudo journalctl -u minecraft.service --since "10 minutes ago" --no-pager | grep 'ViaVersion detected server version'The plugins should appear in the list, and the logs should show your server's version. Then connect with a client on another version, and display the versions in use:
sudo mc-console viaversion listYour username should appear next to your client's version. If nobody is connected, the command responds No players found!.
Finally, try what your players do: place and break blocks, open a chest, use your commands and your main plugins.
Limit the Accepted Versions
The block-versions setting refuses certain versions. This example blocks everything older than 1.20.5:
sudo -u minecraft sed -i 's/^block-versions: .*/block-versions: ["<1.20.5"]/' /opt/minecraft/server/plugins/ViaVersion/config.yml
sudo grep '^block-versions:' /opt/minecraft/server/plugins/ViaVersion/config.yml
sudo systemctl restart minecraft.serviceThe < and > prefixes are accepted, and several values can be listed: ["<1.16", "1.16.4", ">1.17.1"]. A refused player sees the text of the block-disconnect-msg setting.
With a Velocity Proxy
If you use Velocity, install ViaVersion either on the proxy or on the servers, never in both places.
Prefer the Paper servers: the ViaVersion documentation states that anti-cheat plugins may work less well when translation happens on the proxy. Repeat the installation for each server, changing the folder:
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/lobby/plugins 26.3 ViaVersion ViaBackwards
sudo systemctl restart minecraft-lobby.serviceVelocity's modern forwarding refuses clients older than 1.13, so ViaRewind will not give them access in this setup.
Update
Paper replaces plugins at startup from the plugins/update folder. Back up, drop in the new versions, then restart:
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/server/plugins/update 26.3 ViaVersion ViaBackwards
sudo systemctl restart minecraft.serviceUpdate all Via plugins at the same time, as their versions go together. After a new Minecraft version comes out, wait until they support it.
Roll Back
Remove the plugins. The world is not affected, and players on another version will be refused again:
sudo systemctl stop minecraft.service
sudo rm -f /opt/minecraft/server/plugins/ViaVersion-*.jar /opt/minecraft/server/plugins/ViaBackwards-*.jar /opt/minecraft/server/plugins/ViaRewind-*.jar
sudo systemctl start minecraft.serviceThe configuration folders remain in plugins and can be deleted if you do not plan to reinstall these plugins.
Troubleshooting
sudo journalctl -u minecraft.service -n 200 --no-pager | grep -iE 'via|error|exception'"Incompatible client! Please use …"
Translation is not active for this version. Use sudo mc-console plugins to check that the plugins are loaded, and compare the client's version with the Choose the Plugins table. An older client needs ViaBackwards.
"You are using an unsupported Minecraft version!"
This version is blocked by block-versions or block-protocols in plugins/ViaVersion/config.yml.
"This server is only compatible with Minecraft 1.13 and above."
This message comes from Velocity with modern forwarding. This client cannot go through this proxy.
"ViaVersion does not have any compatible versions for this server version!"
ViaVersion is too old for your server. Update it. If the Minecraft version has just been released, wait for a compatible version.
The script says "does not declare support for Paper"
The latest version published on Hangar does not list your Paper version. Check the number passed to the script and the project page. For a very recent Minecraft version, wait a few days.
A Via plugin does not load
| Message | Cause | Solution |
|---|---|---|
Unknown/missing dependency plugins |
ViaVersion is missing for ViaBackwards, or ViaBackwards is missing for ViaRewind | Install the plugin indicated |
Ambiguous plugin name |
Two versions of the same plugin in plugins |
Keep only one file |
UnsupportedClassVersionError |
Java is too old | Install Java 25 |
Ghost blocks or desynced inventory
These discrepancies often come from translation between distant versions. Update the Via plugins and, if needed, limit the accepted versions to exclude the oldest ones.
To go further, see the installation documentation, the configuration documentation, and the project's plugin selection tool.