Fixing BungeeCord's IP forwarding error

This is a BungeeCord-specific error

If you are running Velocity, this error does not apply to you. Velocity uses a signed shared secret in velocity.toml plus a matching setting in paper-global.yml, and it fails differently when misconfigured. See setting up a Velocity proxy network instead.

This guide is for the older, plaintext forwarding scheme that ships with BungeeCord, which is one of the most common proxy setup failures on record: the specific message is "If you wish to use IP forwarding, please enable it in your BungeeCord config as well!", and it means one or more of three separate config files disagree with each other.

One honest note before the fix: Velocity is the community-recommended default now. It is actively maintained by PaperMC, and BungeeCord is not seeing much beyond critical fixes. Waterfall, a BungeeCord fork some networks migrated to, is end of life. If you are starting a network today, start on Velocity. If you already run BungeeCord, migrating is a project of its own, not a two-minute fix, so here is how to actually fix the error you have.

Why the error exists

BungeeCord's proxy connects to your backend servers over plain TCP. By default, a backend has no way to know whether a connection came from your proxy or from anyone else on the internet who found the port. IP forwarding is BungeeCord's way of telling the backend "trust the player identity I am handing you, because I already verified it with Mojang."

That trust has to be turned on in three places, and BungeeCord throws this exact error when a backend server sees a connection claiming to be forwarded but the backend itself was never told to expect it. The message comes from the backend server, not the proxy, which is why editing only config.yml on the proxy so often fails to clear it.

The three files, in full

1. The proxy's config.yml

ip_forward: true

This tells BungeeCord itself to send player IP and identity data downstream instead of letting each backend see the proxy's own connection.

2. Every backend's spigot.yml

settings:
  bungeecord: true

Every server behind the proxy needs this, not just one. This is the setting people miss: a network with a lobby, a survival server and a minigame server needs it in all three spigot.yml files. Missing it on even one server means that server throws the error the moment a player is forwarded to it, while the others work fine, which makes the problem look server-specific when it is really just incomplete.

3. Every backend's server.properties

online-mode=false

Also required on every backend, also for the same reason. The proxy is the one making real contact with Mojang's session servers. If a backend also tries to authenticate a player it has already received through forwarding, that second authentication attempt has nothing to verify against and the connection is rejected.

All three must be true, on every server, at once. Any single file left on its default is enough to produce the error.

Fixing it

1. Open the proxy's config.yml and confirm ip_forward: true.
2. Open spigot.yml on each backend server and confirm settings.bungeecord: true.
3. Open server.properties on each backend server and confirm online-mode=false.
4. Fully restart the proxy and every backend. A /reload does not re-read these files reliably; a restart does.
5. Reconnect and check that usernames and skins forward correctly, not just that the error is gone. A player showing as their real name with the right skin confirms forwarding is actually working, not just silent.

If the error persists after all three are set correctly on every server, check for a leftover reverse proxy, load balancer, or second BungeeCord instance sitting between the proxy you edited and the backend. Forwarding data does not survive an extra unconfigured hop.

A second, related error: chat signature failures

Some BungeeCord networks that have IP forwarding working correctly still see "Invalid signature for profile public key" or "This message is not secure" in chat. This is a different mechanism with a similar root cause.

Since Minecraft 1.19, clients sign their chat messages with a key tied to the player's Mojang profile, and whatever the client is connected to has to correctly relay and verify that signature. Velocity, being actively maintained, implements this relay fully. BungeeCord, being on minimal maintenance, does not always relay the signature correctly between proxy and backend, particularly when enforce-secure-profile is set differently on the proxy than on one or more backends.

The fix: set enforce-secure-profile to the same value everywhere, on the proxy and on every backend server. It does not matter which value you choose as much as it matters that every server in the chain agrees. If chat signature errors persist after that, the cause is BungeeCord's own relay of the signature rather than anything in your config, and Velocity handles this reliably where BungeeCord does not always.

Confirming versions match

A proxy on a different Minecraft version than a backend can produce connection errors that look similar to a forwarding failure but are not. Check what each side actually speaks on the compatibility page before assuming the fix above did not work.