EN

Game servers

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.

6 min read, updated on 18 November 2026

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 with curl and jq
  • SSH access with a user that has sudo privileges
  • 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=0 and above y=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:

Terminal
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/backups

Install the Plugins

Create a script that downloads the plugins from Hangar, checks that they support your Paper version and verifies their checksums:

Terminal
sudo nano /opt/minecraft/via-get.sh
Terminal
#!/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."
done

Replace your-domain.com on the UA line, then make the script executable:

Terminal
sudo chmod 755 /opt/minecraft/via-get.sh

Install the plugins you chose. Here is the most common case, to welcome older clients:

Terminal
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/server/plugins 26.3 ViaVersion ViaBackwards

Add 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:

Terminal
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f

Verify the Result

Terminal
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:

Terminal
sudo mc-console viaversion list

Your 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:

Terminal
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.service

The < 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:

Terminal
sudo -u minecraft /opt/minecraft/via-get.sh /opt/minecraft/lobby/plugins 26.3 ViaVersion ViaBackwards
sudo systemctl restart minecraft-lobby.service

Velocity'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:

Terminal
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.service

Update 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:

Terminal
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.service

The configuration folders remain in plugins and can be deleted if you do not plan to reinstall these plugins.

Troubleshooting

Terminal
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.