server-icon.png: the exact requirements, and the management API nobody uses
64x64, PNG, at the server root — get any of the three wrong and the icon silently does not appear. Plus the JSON-RPC management API that replaced screen-scraping the console.
The server icon is the least forgiving small feature in Minecraft, because every failure mode looks identical: no icon, no error.
Three requirements, all mandatory
- Exactly 64×64 pixels. Not 63, not 128. The server does not resize.
- PNG format. Actually PNG, not a renamed JPG.
- Named
server-icon.png, in the server root — besideserver.properties, not
inside the world folder.
Get any one wrong and the server starts normally and shows the default icon. Nothing is logged at the default level.
Things that also break it
- Interlaced PNG. Some editors save interlaced by default; Minecraft's reader rejects
it. Re-export non-interlaced.
- 16-bit colour depth. Save as 8-bit per channel.
- Colour profiles. An embedded ICC profile occasionally trips the parser. Strip
metadata on export.
- Transparency is fine and renders correctly in the server list.
The client caches it
Once a client has seen your server, it holds the icon. Changing it server-side does not update existing entries — the player has to remove and re-add the server, or wait for the cache to expire. Testing an icon change from your own client will convince you it did not work when it did.
The management API
Recent server versions expose a JSON-RPC management interface, which is the sanctioned replacement for parsing console output or bolting on a plugin.
Enable it in server.properties:
management-server-enabled=true
management-server-host=localhost
management-server-port=25585Then speak JSON-RPC over that port:
{ "jsonrpc": "2.0", "id": 1, "method": "minecraft:players" }Methods cover the player list, server status, allowlist and ban list, gamerules, settings, and a save/stop pair. Each returns structured JSON instead of a line of text you have to regex.
Bind it to localhost
The default is localhost and it should stay there. The interface is not intended to face the internet — anything reaching it can stop your server. Expose it through an SSH tunnel or a reverse proxy with authentication if you need remote access, never by changing the host to 0.0.0.0.
Why it matters
Dashboards, Discord bots and uptime monitors have historically worked by reading the console log or using RCON, both of which are fragile. A typed API means a player-count widget does not break when a log line changes format.
Convert any image into a compliant server-icon.png and browse the JSON-RPC methods in the Server Icon & API Tools.