How to Set Up Waterfall for a Minecraft Proxy Server

What Waterfall Is Used For

Minecraft networks usually run more than one backend server. A lobby, survival world, minigame server, and creative server should not all be crammed into the same server directory unless you enjoy mysterious file conflicts as a hobby. A proxy sits in front of those backend servers and routes players to the right place.

BungeeCord has long been a common proxy choice for this setup. Waterfall is a drop-in alternative built by the same team behind Paper, with a focus on stability, scalability, and extra configuration options. It is still designed around the BungeeCord ecosystem, so existing BungeeCord networks can usually move to Waterfall without rebuilding the whole setup.

This guide covers how to switch a Minecraft proxy server to Waterfall and what the main Waterfall-specific settings do.

Before Installing Waterfall

Waterfall is hot-swappable with BungeeCord. If the proxy is already configured and your backend servers are connected, switching the proxy software should not require a full reconfiguration.

If this is a new network, configure the proxy basics first, including backend server entries, player forwarding, permissions, and listener settings. Waterfall can only route players correctly when the network itself is already mapped out.

Installing Waterfall on Your Proxy Server

The exact panel layout depends on your hosting provider, but the process is usually simple:

1. Open your server control panel.
2. Stop the proxy server before changing the server software.
3. Find the server JAR or software selection menu.
4. Choose Waterfall from the available proxy options.
5. If the panel asks whether to reset the world, either option is normally fine for a proxy because proxies do not load Minecraft worlds.
6. Save the change and start the server again.

After startup, the proxy should now be running Waterfall. If the server was already using BungeeCord and the configuration files were left in place, your existing network settings should continue working.

Important Waterfall Settings

Waterfall adds a `waterfall.yml` file with several useful settings. Most networks can leave the defaults alone at first, but knowing what they do makes troubleshooting much easier.

use_netty_dns_resolver controls whether Netty's asynchronous DNS resolver is used during account authentication. The default value is `true`.

disable_modern_tab_limiter removes the tab completion limit for Minecraft 1.13 and newer clients. This is set to `true` by default.

log_initial_handler_connections determines whether InitialHandler connections are written to the logs. The default is `true`, which can help when diagnosing connection attempts.

game_version changes the supported version text shown to players in the Minecraft client. By default, Waterfall reports the versions it detects. A network might display something like `1.14.x, 1.15.x, 1.16.x`.

disable_entity_metadata_rewrite disables entity metadata rewriting and sends a join packet to the client instead. This can be more reliable for some modded networks, but it may break certain plugins. The default is `false`.

disable_tab_list_rewrite turns off tab list rewriting. This may help with player profile issues when Waterfall is running in offline mode. The default is `false`.

Final Notes

Waterfall is a strong choice for Minecraft networks that need a BungeeCord-compatible proxy with additional stability and tuning options. For small networks, the default configuration is often enough. For larger networks, `waterfall.yml` gives administrators a few extra knobs to turn without needing to replace the entire proxy setup.