The Minecraft server list ping, end to end

When your server shows the wrong player count on a listing site, or the MOTD renders as a block of raw JSON, or the icon never appears, the cause is almost always in a five-packet exchange that takes about a millisecond and that nobody has ever looked at.

It is called Server List Ping, and the Minecraft Wiki documents it in full. Knowing its shape turns three common mysteries into ordinary bugs.

The exchange

Five steps, in order:

1. The client sends a handshake with the "next state" field set to 1. That value is the whole difference between "I am about to ask you a question" and "I am about to join". A server that is up but refusing logins will still answer a status query.
2. The client sends an empty status request.
3. The server replies with a status response: one JSON document.
4. The client sends a ping carrying a payload, usually a timestamp.
5. The server echoes the same payload back as a pong, and the connection closes.

The latency number a listing shows is measured between steps 4 and 5. It is a TCP round trip to your server from wherever the poller sits, and it is not the latency your players will feel unless they happen to live beside the poller. A listing that shows you at 180ms is telling you where it is, not how your server plays.

That distinction is worth holding onto, because it is the same one that makes picking a host region a decision about your players rather than about a number on a dashboard.

What is in the JSON

The status response carries a small set of fields:

• version, an object with a name string such as "1.21.8" and a numeric protocol
• players, with max, online, and an optional sample array
• description, the MOTD, as a text component
• favicon, an optional base64-encoded 64×64 PNG
• enforcesSecureChat, a boolean

The wiki notes that the name field of the version object "should be considered mandatory" and that description "should be a text component".

Those two sentences explain most of the bugs.

Three mysteries, solved

The MOTD renders as raw JSON or loses its colours. description is a text component, not a string. Some proxies and plugins write a bare string there, which older clients tolerate and newer parsers do not. If your MOTD looks right in the vanilla client and wrong on a listing, the listing is parsing it strictly and your server is emitting the lenient form.

The version shows as "unknown". Something is omitting version.name, or writing a value that is not a version string. Proxies do this when configured to report the backend rather than themselves. It matters more than it looks: a listing that cannot read your version cannot file you under one, and being filed correctly is most of what claiming and maintaining a listing is for.

The icon never appears. favicon is strict: 64×64, PNG, base64, with the data URI prefix. A 128×128 image is not scaled for you: it is rejected, silently, and you are left assuming the listing does not support icons.

The sample array, and why it is usually empty

players.sample is optional and capped. Most servers with real populations either omit it or return a handful of names. It is the field people expect to be a player list and it has never been one.

If you are trying to work out why your listed count disagrees with reality, the count is players.online, reported by your server, at the moment it was asked. A listing polling hourly shows you an hour-old number. That is not the listing being wrong, and it is worth understanding before concluding your listing is broken.

Why any of this is worth your time

Two of the three bugs above are invisible from inside the game. Your players see a correct MOTD, a correct icon and a correct version, because the vanilla client is forgiving in exactly the places a strict parser is not. The only place they surface is on the listings, which is to say, in front of everyone who has not joined yet.

If yours looks wrong somewhere public, the packet is the first place to look, not the last. The same reasoning applies to the Source-engine side of the house, where a query that returns nothing has its own short list of causes.