Velocity does not support re-entering the configuration phase from play.

[mworzala]

Expected Behavior

I expect the server to be able to send the client back to configuration and bring them back to play without issue.

Actual Behavior

The server recieves an invalid packet and disconnects the client.

Error message from an unmodified vanilla server

[13:50:31] [Server thread/INFO]: notmattw (9f36238e-bee0-3e4e-9404-44efe6986143) lost connection: Internal Exception: io.netty.handler.codec.DecoderException: Received unknown packet id 12

Also error message from a Minestom server

java.lang.IllegalStateException: Packet id 0x1d isn't registered!
	at net.minestom.server.network.packet.PacketRegistry$PacketRegistryTemplate.packetInfo(PacketRegistry.java:482)
	at net.minestom.server.network.packet.PacketReading.readPayload(PacketReading.java:210)
	at net.minestom.server.network.packet.PacketReading.readFramedPacket(PacketReading.java:187)

Steps to Reproduce

Start velocity pointing at a vanilla server with debug commands enabled, eg

java -DMC_DEBUG_ENABLED -DMC_DEBUG_DEV_COMMANDS -jar server.jar nogui

1. join the server through velocity
2. Force yourself into the configuration state, eg debugconfig config <your_username>
3. Force yourself back into the play state, eg debugconfig unconfig <your_uuid>
4. Observe above error message in server logs and disconnect
5. Become sad :-(

Note its easier to reproduce with some latency (eg 200ms), not sure if its required

Plugin List

No plugins on either velocity or server (vanilla server)

Velocity Version

running on commit 5320aae (from 26/1/26)

[13:58:54 INFO]: Velocity
[13:58:54 INFO]: Copyright 2018-2026 Velocity Contributors. Velocity is licensed under the terms of the GNU General Public License v3.
[13:58:54 INFO]: PaperMC - GitHub

Additional Information

I believe the issue is to do with the packet queue logic that occurs. When you enter config it starts queuing received play packets (most typically a tick end packet, 0xc). When the server sends a finish configuration packet, MinecraftConnection#setState is called which sends all those queued packets immediately. The result is the server receiving the play packets before the finish config ack from the client, and failing to parse them (it's still looking for play packets).

Im not sure if the fix is as simple as deleting the queuing mechanism or not, but it does not make sense to send play packets from before reconfiguring after the reconfiguration ends. They should be forwarded immediately or worst case dropped. Sending them after reconfig is likely to cause issues with any reasonable anticheat (eg imagine receiving an attack after reconfigured where you may be hundreds of blocks away from the person you 'attacked').

[electronicboy]

The queue handling logic was a bit handholdy, a lot of the handling for this phase was honestly a "get it out the door"

I want to find the time to do a major version bump to just redo a whole bunch of this stuff, this is mostly intended for mitigating plugin API related things, so the queue can probably go

[BomBardyGamer]

For your interest, our fix for this was hollow-cube@11f99c5

I found that, for our use case, it fully worked without the packet queue, but I thought making sure it queues packets on first run was more like the expected behaviour for this functionality. I can PR this upstream if this is a reasonable change, though it probably needs some more testing with some plugins and a vanilla server.

[electronicboy]

Maybe worth a config option that is defaulted to off? Not that adding config options really works well right now, but deprecate it and let plugins deal with upgrading before I yeet it whenever somebody finds the time to do an overhaul here

NB: by that, I mean disabling the queue by default, it was a kinda silly thing trying to keep some plugins working in a case they likely didn't work reliably inside of anyways, probably better to just be rid of it

[Gerrygames]

I think only the outbound queue should be enabled in ConnectedPlayer#switchToConfigState.

[ZECHEESELORD]

Hello!
I took a peek into this and it turned out to be two separate problems.

The first one is on the Velocity side, which matches the original suspicion in this issue. On the connected PLAY -> CONFIG path, Velocity was still using full play queueing semantics and was too trusting about forwarding client traffic back to the backend. (serverbound play traffic could be replayed after the handoff, and generic packets could still be forwarded even when the backend was no longer actually in PLAY.)

See #1747- It switches this path to outbound only queueing, keeps generic/unknown forwarding gated on the backend actually being in PLAY, and only forwards keepalives when client and backend states match.

That being said, the patch fixed the proxy side issue, but it did not fully explain the timeout on its own. While testing it, I was able to locate a second bug in Paper- the keepalive tracker is carried across listener handoff from PLAY to CONFIG. Under latency, the configuration listener can inherit a stale PLAY expectation and reject the first CONFIG keepalive reply as out of order.

With the Velocity patch plus the Paper side handoff fix, I have not been able to reproduce the failure anymore, including with added latency (0ms, 50ms, 100ms, 500ms, 800ms).

[ZECHEESELORD]

small followup-
The timeout path ended up being even more specific than I thought from the earlier proxy debug logs:

On the failing repro, the backend sequence was:

1. the PLAY listener issued keepalive A
2. listener handoff moved the player into the CONFIG listener, but the old pending keepalive expectation was still carried over
3. the CONFIG listener issued keepalive B
4. the backend received reply B
5. the backend rejected B as stale/out-of-order, because the inherited pending expectation was still A

See PaperMC/Paper#13712 for fixes + explaination.

With that Paper patch applied, I have not been able to reproduce the timeout anymore, including with added latency. Tested with 0ms, 50ms, 100ms, 500ms, 800ms.