How to Set Up ViaVersion on a Paper Server

Choose the direction of compatibility first

ViaVersion translates Minecraft Java network protocols; it does not upgrade the server software or add gameplay from another release. The base plugin lets newer supported Java clients connect to an older supported server. A client can still use only the blocks, entities, commands and mechanics the server understands. Treat that distinction as the design rule: protocol compatibility can widen access, but the Paper version remains the authority for world data and gameplay.

If the Paper server is newer than the clients you want to admit, ViaVersion alone is the wrong direction. Install ViaBackwards alongside it to let supported older Java clients join a newer server. ViaBackwards requires ViaVersion and documents limitations where old clients cannot represent newer world heights, items, sounds or interfaces exactly. Do not promise full feature parity to players, and do not advertise a version until that exact client-to-server path has passed a real join test.

Write a small matrix before maintenance: the native Paper version, the newest client that must join, the oldest client that must join, and any proxy in front. Avoid an unlimited 'all versions' goal. A narrow supported range is easier to secure, reproduce and retire. Check the live compatibility table and release notes because support follows protocol work and a new Minecraft release may arrive before a stable ViaVersion build.

• Newer client to older Paper: install ViaVersion.
• Older client to newer Paper: install ViaVersion plus ViaBackwards.
• Gameplay and world features remain those of the Paper server version.
• Publish only client versions that have passed your own connection matrix.

Prepare Paper and install the official plugin

Record the Paper build, Minecraft version, Java runtime, plugin list and working native-version join. ViaVersion currently requires Java 17 or newer, while the Paper release itself may require a newer runtime. Satisfy both projects rather than lowering Java for one old client. Stop Paper cleanly and take a restorable backup of worlds, configuration and plugin data before changing the network protocol layer.

Download the current ViaVersion plugin from the project's official Hangar page or GitHub releases. Follow the artifact checks in /blog/install-plugins-paper-minecraft-server: confirm the project owner, supported platform, release notes and file before it reaches production. With Paper stopped, place one ViaVersion JAR directly in the plugins directory. Remove an older active copy from that directory, but preserve it with the backup for rollback.

Start Paper normally and read the log from the first line. ViaVersion should enable and create plugins/ViaVersion/config.yml. Run /viaversion from the console or an authorized account and confirm the reported build. Do not use /reload or a plugin manager to introduce or update it; ViaVersion's own installation guide warns that a full reboot is required for reliable behavior. If the plugin is red, missing or reports a Java error, fix that installation before testing a second client version.

• Back up the stopped server and record the known-good native join.
• Use one official Paper-compatible ViaVersion JAR.
• Verify the generated configuration and complete startup log.
• Restart fully for installation and upgrades; never depend on /reload.

Add ViaBackwards only for older clients

Install ViaBackwards only when the matrix includes clients older than the Paper server. Download its matching official plugin release, stop Paper, and place its JAR beside ViaVersion in plugins. ViaBackwards will not operate independently: its project explicitly requires ViaVersion. Start again and confirm that both plugins enable without a dependency or mapping error.

Keep the pair aligned to compatible current releases. ViaVersion and ViaBackwards commonly publish together, but release numbers and support can change, so verify both release pages rather than assuming two files with similar names match. Avoid piling on ViaRewind, ProtocolSupport or protocol add-ons unless the matrix genuinely requires them and their current documentation describes the combination. Every extra translator expands the test surface.

Test in increasing complexity. Join first with the exact native server version, then a newer client handled by ViaVersion, and finally each older client handled by ViaBackwards. Use ordinary accounts, move through existing and newly generated terrain, interact with containers, chat, commands, resource packs and any inventory-heavy plugins. Reconnect after a server restart. A successful server-list ping is useful, but it is not an acceptance test for play.

• Native client proves Paper still works without translation.
• Newer client proves the ViaVersion direction.
• Older client proves the ViaBackwards direction and its limitations.
• Real movement, inventory and reconnect tests catch more than a green ping.

Configure an explicit supported range

ViaVersion works with its generated defaults, so begin from the generated plugins/ViaVersion/config.yml rather than copying a stale example. Preserve its comments and use spaces, not tabs, because it is YAML. Keep update checks enabled so operators see compatibility fixes promptly. Change one setting at a time, restart when the option requires it, and retain the previous file for comparison.

Use block-versions when the technical translation range is wider than the range you are prepared to support. The configuration accepts version names and comparisons such as a less-than boundary. That lets you retire clients with known plugin, moderation or gameplay problems while keeping a clear disconnect message. Prefer readable version rules over raw protocol numbers unless an exact protocol edge is necessary, and verify the rule with a client on both sides of the boundary.

Do not casually disable the built-in packet limiter or suppress conversion warnings to make a disconnect disappear. Those controls exist to limit abusive traffic and expose mappings that could not be translated. First reproduce the issue, capture the client/server versions and inspect /viaversion pps or the log. Only tune a limiter after measured legitimate traffic demonstrates a false positive, and keep the smallest justified change.

• Start with the generated configuration and keep its comments.
• Block versions outside the tested support policy explicitly.
• Test both an allowed and a rejected client after changing a boundary.
• Investigate warnings and packet rates before weakening safeguards.

Place translation once in a proxy network

A Paper server behind Velocity needs one deliberate translation layer. ViaVersion's installation guide says to install it either on the proxy or on the backend servers, not both. Proxy placement centralizes client handling, while backend placement gives the translator direct server state and can behave better with mechanics and anti-cheat. Choose based on the network's actual plugins and support policy, then document the choice.

If ViaVersion runs on Velocity, keep Velocity current and let it detect backend protocol versions. The configuration provides probe and ping behavior for proxy servers; /viaversion probe can refresh the known backend versions. Test switching between every backend, not just joining the lobby. An incorrect backend mapping can let login succeed and fail only when a player changes servers.

ViaVersion handles Java protocol versions, not Bedrock transport or authentication. A Geyser connection remains a separate compatibility path with its own supported versions, ports and tests. Likewise, ViaVersion is not a substitute for updating Paper, plugins or Java. Keep the layers separate in incident notes so a Java translation failure does not get diagnosed as a Bedrock, proxy or world problem.

• Install ViaVersion on the proxy or the backends, never both by accident.
• Keep Velocity current and verify every server switch in the network.
• Test Geyser and other gateways as separate connection paths.
• Record exactly where translation occurs for future troubleshooting.

Diagnose outdated-server and packet errors

For an Outdated Server message, confirm the player reached the intended address, then compare the client, Paper and ViaVersion versions with the current support table. Check that the plugin enabled on the actual translation layer and that a proxy is not routing to a different backend. Very new Minecraft clients may need to wait for a stable ViaVersion release; the project states that non-trivial protocol updates can take several days after a game release.

Use /viaversion list to see connected client versions and /viaversion player for one connection. The pps command helps investigate packet-rate kicks. When support needs a complete snapshot, /viaversion dump creates a link containing useful environment information; review it before sharing and never add secrets, private logs or credentials. Debug and Netty leak detection are specialist tools, so enable them only for a bounded reproduction or when the project asks.

For strange packet errors, reproduce on a clean supported client and inspect plugins that modify packets, inventories, scoreboards, anti-cheat or custom items. Update one suspect at a time and repeat the same action. Do not hide the warning, grant operator or remove authentication as a shortcut. If the native client works but one translated client fails at a repeatable action, preserve the exact disconnect text, timestamp and stack trace for a focused report.

• Outdated Server: verify endpoint, layer, release support and startup state.
• Packet kick: capture the action, client version, PPS and server timestamp.
• Single-action failure: isolate packet-changing plugins one at a time.
• Support report: include a reviewed dump and exact logs, never credentials.

Update the compatibility layer without surprises

Treat ViaVersion releases as network changes. Read the release notes for ViaVersion and ViaBackwards, stage the pair against a recent server backup, and rerun the connection matrix before production. The current 5.12.0 releases add Minecraft 26.3 protocol support and include fixes for translated items, movement and other version edges; that is a reason to test the affected paths, not a reason to skip testing.

Keep the prior JARs, generated configurations and acceptance results through a rollback window. If an update fails, stop Paper and restore the known compatible plugin set together rather than mixing versions at random. Recheck the native client after rollback so a protocol change is not confused with an unrelated Paper or proxy failure.

Review the supported range after every Paper, proxy or Minecraft release. Retire versions that no longer meet the community's plugin and moderation requirements, and tell players the tested range instead of promising permanent compatibility. More operational guides are collected at /blog. If maintaining several versions needs isolated staging, dependable backups or a better-supported runtime, compare the documented plans at /pricing after defining the smallest range your community actually uses.