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. A wrong size or a file that is not really a PNG does log one line at startup — Couldn't load server icon — but a misnamed or misplaced file logs nothing. (With no server-icon.png at all, the server falls back to the world's own icon.png if there is one.)
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 server reads it once
The server loads server-icon.png when it starts and never again. Replacing the file on a running server changes nothing until a restart — which is why testing an icon change without restarting will convince you it did not work. After a restart, a client picks up the new icon on its next server-list refresh.
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=25585
management-server-tls-enabled=falseTLS is on by default and needs a keystore (management-server-tls-keystore), so either point it at one or — on localhost only — turn it off as above; with TLS on and no keystore the management server does not start. The port has no default either (25585 is just an example).
Then open a WebSocket to that port, sending the management-server-secret from server.properties as Authorization: Bearer <secret>, and speak JSON-RPC:
{ "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 — anyone who reaches it with the secret can stop your server, and the secret is only as safe as your server.properties. 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.