--- title: "Setting Up ViaVersion for Cross-Version Compatibility | ZCS" description: "A server running one Minecraft version normally can't be joined by clients on a different one. ViaVersion is the plugin that removes that restriction." url: "https://www.zcraftstudios.com/blog/viaversion-cross-version-setup" updated: "2026-10-20T07:15:13.005688+00:00" source: "ZCraft Studios" --- > Site index for AI agents: https://www.zcraftstudios.com/llms.txt (full reference: https://www.zcraftstudios.com/llms-full.txt). Every page is available as Markdown by adding `.md` to its URL or sending `Accept: text/markdown`. 1. [Home](https://www.zcraftstudios.com/) 2. [Blog](https://www.zcraftstudios.com/blog) 3. Setting Up ViaVersion for Cross-Version Compatibility [ All posts](https://www.zcraftstudios.com/blog) # Setting Up ViaVersion for Cross-Version Compatibility ZCraft StudiosOct 3, 2026Updated Oct 20, 2026 A server running one Minecraft version normally can't be joined by clients on a different one. ViaVersion is the plugin that removes that restriction. ## In this guide - [Install ViaVersion](#install-viaversion) - [Supporting Older Clients](#supporting-older-clients) - [Checking Supported Versions](#checking-supported-versions) - [Using It on a Proxy](#using-it-on-a-proxy) - [Checking a Player's Actual Protocol Version](#checking-a-players-actual-protocol-version) - [Common Limitations](#common-limitations) - [Why This Matters for a Public Server](#why-this-matters-for-a-public-server) - [Build a compatibility test matrix](#build-a-compatibility-test-matrix) - [Client version communication](#client-version-communication) - [Official documentation and links](#official-documentation-and-links) - [An operational test worth running](#an-operational-test-worth-running) ## Setting Up ViaVersion for Cross-Version Compatibility _Without it, a player one version behind (or ahead) simply can't connect. It's a hard block, not a warning._ By default, a Minecraft server only accepts clients running the exact same version. ViaVersion translates the protocol so clients on newer (or, with an additional plugin, older) versions can still connect to a server running a different version. ## Install ViaVersion [ViaVersionAllow newer Java Edition clients to connect to older servers.On Modrinth ](https://modrinth.com/plugin/viaversion) Download ViaVersion from the project linked above. Check the supported Minecraft version, server platform, Java requirement and dependencies for the selected release. 1. Back up the server files and any plugin database. 2. Stop the server before changing JAR files. Put the compatible plugin build and its required dependencies in the correct plugin folder. 3. Start the server and read the startup log. Resolve missing dependencies or version errors before editing the generated configuration. 4. Stop the server, make one small configuration change, then restart and test it with a non-operator account. ViaVersion enables supported newer clients on older servers. Add ViaBackwards only when older clients also need access, and check the supported protocol range. ## Supporting Older Clients ViaVersion by itself lets **newer** clients join an **older** server version. For the reverse (older clients joining a newer server), a companion plugin, ViaBackwards, is needed alongside it: ``` plugins/ ViaVersion.jar ViaBackwards.jar ``` ## Checking Supported Versions ``` /viaversion ``` reports the plugin's version and the protocol range it currently supports. This changes as new Minecraft versions release and ViaVersion adds support for them. ## Using It on a Proxy On a Velocity or BungeeCord network, ViaVersion is best installed at the **proxy level** rather than on each individual backend server, since this translates protocols once, centrally, instead of configuring it separately on every backend. ## Checking a Player's Actual Protocol Version ``` /viaversion dump ``` generates a diagnostic report, useful when troubleshooting a specific player's connection issue. It shows exactly what protocol version they connected with versus what the server expects. ## Common Limitations - **Very new client-only features** (new blocks, items, or mechanics added in a version the server doesn't run) obviously can't be translated into something that doesn't exist on the server. ViaVersion bridges protocol compatibility, not missing content. - **Plugin compatibility isn't guaranteed**: a plugin that hard-codes assumptions about a specific Minecraft version can behave unexpectedly with clients ViaVersion is translating, though this is increasingly rare with modern, well-maintained plugins. - **Performance overhead is minimal** for most servers, but very high-player-count networks with many different client versions connected simultaneously should monitor performance after enabling it. ## Why This Matters for a Public Server Minecraft updates often enough that requiring every player to be on the exact same version as the server meaningfully shrinks the available player base, and ViaVersion is one of the most commonly installed plugins specifically to avoid that problem. ## Build a compatibility test matrix Cross-version plugins can help different client versions connect, but they do not magically add every feature from a newer Minecraft release to an older server. Protocol translation and gameplay compatibility are different things. | Test | What to verify | | --- | --- | | Oldest supported client | Can connect and move normally | | Newest supported client | Can interact with blocks and inventories | | Chat and commands | Text appears correctly, with no disconnects | | Plugin GUIs | Custom menus work for supported clients | | Combat and entities | No obvious interaction or animation issues | | Proxy and backend | Compatible ViaVersion components where applicable | After installation, record which client versions you actually tested. Clearly publish that supported range instead of promising every version. Check the [ViaVersion project](https://github.com/ViaVersion/ViaVersion) for current build compatibility and installation guidance. ## Client version communication Display the tested client version range clearly on your server website or Discord. Re-test inventories, entities and plugin GUIs after major upgrades; translation support does not guarantee identical mechanics on every client version. [ViaVersionAllow newer Java Edition clients to connect to older servers.On Modrinth ](https://modrinth.com/plugin/viaversion) _ViaVersion project artwork. [Official source](https://github.com/ViaVersion/ViaVersion). Illustrative publisher image._ ## Official documentation and links - [Official project repository](https://github.com/ViaVersion/ViaVersion) - [How Often to Update a Minecraft Server](https://www.zcraftstudios.com/blog/minecraft-server-updates) [ViaVersionAllow newer Java Edition clients to connect to older servers.On Modrinth ](https://modrinth.com/plugin/viaversion) ## An operational test worth running Test the exact older and newer client versions you intend to support. Successful login does not guarantee every interface, item behavior or anti-cheat integration works normally. Verify supported version ranges in project release notes and avoid claiming compatibility with future Minecraft updates until tested. ## Continue reading - [Setting Up Geyser and Floodgate for Bedrock Cross-Play](https://www.zcraftstudios.com/blog/geyser-floodgate-bedrock-crossplay-setup) [ Previous guide Creating NPCs With Citizens: A Setup Guide](https://www.zcraftstudios.com/blog/citizens-npc-setup-guide)[ Next guide Run a Minecraft Server With Docker: Setup Guide](https://www.zcraftstudios.com/blog/docker-minecraft-server-setup)