ViaVersion tasks

Task guides and troubleshooting for ViaVersion. Check the installed release before changing configuration or data.

Set a deliberate Java client policy with ViaVersion version blocks

Accepting a protocol does not mean you want to support it. A community may choose a smaller client range because its resource pack, combat rules or accessibility testing covers only those clients. ViaVersion provides readable version blocks without changing the server world.

Record the starting point

Write down the native server version, the oldest and newest clients you intend to allow, and the installed ViaVersion build. Keep the current configuration and prepare one allowed client plus one intentionally excluded client. Use a quiet test window rather than excluding everyone during an event.

Work through the change

  1. Open the active ViaVersion configuration and locate its generated block-versions and block-protocols options. Read the comments supplied by the installed release before changing either list.
  2. Add only the intended readable version restriction to block-versions. Existing numeric blocks also apply, so inspect both lists when a client appears to be excluded unexpectedly.
  3. Set a concise blocked-client message using the documented message option. Tell players which client range to use; do not claim they have been banned from the community.
  4. Restart normally and test the two prepared clients through the public connection route. On a proxy network, repeat the check for each backend whose supported range differs.

Check the result

The allowed client should join and perform normal movement and inventory actions. The excluded client should receive the intended explanation before entering gameplay. Record the effective range alongside the release numbers so a future upgrade can repeat the same acceptance test.

If the result differs

An allowed client failing too may indicate overlapping numeric blocks, a restriction on another network component or a missing translation dependency. Compare the rejection text and startup log. Do not loosen every restriction simply because one version was entered incorrectly.

Restore the saved restriction lists and restart if the policy prevents the intended population from joining. Keep a copy of the failed rule for review. Changing an admission rule does not require changing player files or regenerating a world.

References and related help

Locate the translation layer in a Velocity network

A network can translate client traffic at a proxy or at supported backend installations. Adding another copy everywhere makes the topology harder to understand and does not guarantee broader support. First establish which component sees the original client and which version each backend actually runs.

Record the starting point

Draw the public proxy, lobby and destination servers on paper. Record their software builds and the Via plugins installed on each. Keep forwarding credentials out of this diagram. Include a working backend as a comparison, because the same client can expose different compatibility requirements across destinations.

Work through the change

  1. Check startup logs to identify active ViaVersion installations and their platform. A JAR sitting in a folder is not proof that the plugin loaded successfully.
  2. Compare the arrangement with the current ViaVersion platform guidance. For Velocity, inspect backend version detection in the generated configuration rather than assuming every destination uses the lobby version.
  3. Join through the normal public proxy with the affected client and transfer to each backend. Record which transfer fails and the corresponding proxy and backend timestamps.
  4. Trial a corrected supported placement on a private copy or controlled maintenance window. Change one translation location at a time and preserve protected backend forwarding.

Check the result

The chosen client should reach every destination you claim to support, and logs should identify one understood translation path for each hop. A successful lobby login alone is insufficient evidence. Include a native-version client in the test so the change does not hide a basic forwarding problem.

If the result differs

A failure on one destination suggests its version detection, plugin requirements or unsupported protocol direction needs checking. Authentication or forwarding errors are a separate issue. Installing ViaBackwards cannot repair a proxy secret mismatch or a backend listening on the wrong address.

Return to the recorded placement if the trial creates new failures. Leave direct backend access protected and retain both sides of the transfer log. Do not reset the network, player databases or login mode merely to simplify a compatibility diagram.

References and related help

Test translated items before publishing a Java resource pack

ViaVersion translates network protocol data; it is not a resource-pack converter. A custom item that looks correct on the native server client can display a fallback model or different behaviour on another supported version. Check the cosmetic feature itself rather than treating a successful login as complete compatibility.

Record the starting point

Prepare a small private test area containing the exact items, menus and interactions used by your pack. Record the pack release and its intended client versions. Keep the existing pack URL and hash so the previous presentation can be restored without changing inventories.

Work through the change

  1. Use the native server client to confirm that the resource pack downloads and that the test item works before involving translation. A broken download is independent of ViaVersion.
  2. Repeat with the oldest and newest clients in your published support range. Accept the pack where supported and compare inventory icons, held models, placement and menu clicks.
  3. Record a fallback as a presentation limitation rather than replacing the real item with a different identifier on the live server. Ask the pack or custom-item maintainer about its supported client formats.
  4. Decide whether to publish the limitation, adjust the pack through its documented process, or narrow the permitted client range. Retest after the chosen change.

Check the result

Players should know which versions receive the full presentation and which receive a fallback. Verify that clicking or moving the item does not duplicate it or lose it during the trial. Keep screenshots labelled with client versions so two different renderers are not mistaken for changing server data.

If the result differs

If every client sees the wrong model, inspect the resource-pack URL, hash and pack configuration first. If only translated clients differ, collect the client version, item plugin build and ViaVersion build. Avoid submitting a full paid resource pack in a public issue.

Restore the previous pack reference if the updated asset breaks the native client. Keep the test items isolated and remove only those created for the trial. Do not roll back an entire player inventory because a model rendered incorrectly.

References and related help

Update the Via plugin family as a tested release set

ViaBackwards and ViaRewind depend on the Via translation chain. Updating one library while retaining an incompatible companion can fail at startup or break only the oldest client. Treat the installed family as a tested set, while keeping server and Java compatibility in view.

Record the starting point

Record all Via plugin filenames and release numbers, the server platform, Java runtime and advertised client range. Download releases from their maintainers. Preserve the current JARs and configuration outside the active plugins directory; duplicate JARs in that directory can make loading ambiguous.

Work through the change

  1. Read the release requirements for the target ViaVersion, ViaBackwards and ViaRewind builds. Include only components your client range needs and check support for the server platform.
  2. Stop the server normally, replace the selected artifacts and retain existing configuration unless the release notes require a documented migration. Do not use a plugin hot-loader for the update.
  3. Start and read the first dependency or startup error before testing players. Resolve a failed companion load rather than continuing because the main server reached its ready message.
  4. Test a native client, a newer translated client and the oldest client you advertise. Exercise inventory movement, world travel and a representative menu rather than checking the server list alone.

Check the result

Every required component should report a successful load, and each test client should complete the same small gameplay checklist. Save the final release combination with the test date. This gives staff a known working baseline when the next Minecraft client update arrives.

If the result differs

A missing class or incompatible API error after replacement usually deserves a dependency comparison before configuration changes. If one client fails, confirm its protocol direction is supported by the installed chain. A development snapshot may not provide the same support as a stable release.

Stop and restore the previous matching set if a required client regresses. Retain the failed startup log and new artifact names for reporting. Do not downgrade the world or delete player data as a workaround for an incompatible translation library.

CloudExa game panel file manager
Use the file manager for the specific configuration file described in this guide; the screenshot shows the panel, not a plugin interface.

References and related help

Investigate packet-rate kicks without disabling every guard

A packet-rate kick can follow a client action, a plugin loop or an unusual network condition. Raising every limit hides the evidence and can remove useful protection. Establish the exact kick message and the action that precedes it before editing any rate-control setting.

Record the starting point

Record the affected client version, ViaVersion release and installed packet-related plugins. Keep the current generated configuration. Choose a consenting tester and a quiet area; reproducing a packet flood with the whole player base online is not necessary to identify a repeated action.

Work through the change

  1. Capture one disconnect timestamp and the complete relevant message from the console. Distinguish a ViaVersion message from a proxy, anti-cheat or server-native packet restriction.
  2. Repeat the suspected action once with the native server client and once with the affected translated client. Note whether joining, inventory use, movement or another action triggers the problem.
  3. Compare the installed release's documented packet settings and compatibility notes. If a dependent plugin is implicated, reproduce on a private copy with that integration changed rather than disabling protections publicly.
  4. Apply only a justified, bounded setting adjustment or compatible plugin update. Retest the same action and an ordinary session, then watch whether the error reappears under normal traffic.

Check the result

The tester should complete the action without a repeated disconnect, while the reason for any changed limit remains documented. A lower player count during testing can conceal the original pattern, so retain the exact steps and check them again during a representative session.

If the result differs

If the kick survives with native and translated clients, examine the originating plugin or proxy before editing ViaVersion again. If it occurs only with one client build, include that build and a minimal reproduction in the maintainer report. Do not publish player addresses from raw connection logs.

Restore the original limit when an adjustment does not change the symptom. Keep the captured evidence and revert the isolated trial plugin change. A rate-limit investigation should not involve changing world files, authentication mode or unrelated host firewall rules.

References and related help

Prepare a useful ViaVersion support report without leaking configuration

A useful compatibility report explains which client, server and translation path failed. A screenshot of a disconnect message rarely supplies enough context. Conversely, posting an entire panel archive can expose unrelated credentials. Build a small report that a maintainer can reproduce without accessing your service.

Record the starting point

Write down the server platform and build, Java version, ViaVersion family releases and affected client version. Identify whether the client connects through a proxy. Keep the original error locally, including its timestamp, and separate account or address information from the technical reproduction.

Work through the change

  1. Reproduce the issue using one short sequence of actions. Include the expected behaviour, actual result and whether the native server client behaves differently.
  2. Use the diagnostic or dump facility documented for your installed ViaVersion release if support requests it. Read the output before sharing its link; generated reports may expose plugin and network details.
  3. Add only the relevant startup or disconnect excerpt. Redact passwords, tokens and unrelated player information without removing version numbers or the first error in the stack trace.
  4. Check the maintainer's issue template and search for the same server/client combination. Submit one report with the minimal reproduction instead of multiple reports containing different guesses.

Check the result

A reader should be able to identify the protocol direction, components involved and exact failing action. Keep a private copy of the report and its original logs so staff can answer a follow-up without asking the player to repeat the failure repeatedly.

If the result differs

If the reproduction disappears after removing a packet-dependent plugin on a test copy, include that comparison. It does not prove either maintainer is at fault, but it narrows the interaction. If no clean reproduction exists, say which observations are confirmed and which remain uncertain.

Remove a public diagnostic link where the hosting tool allows it if you discover a secret after sharing. Rotate an exposed credential rather than assuming deletion removed every copy. Keep gameplay configuration unchanged while preparing the report.

References and related help