Repository navigation
Troubleshooting
Start with /metrics on the exporter: most answers show there.
- “nothing to read: set WORLDAPI_URL, or EXPORTER_TARGETS for /probe”. Set at least one of them.
-
“should end in /api/v1”.
WORLDAPI_URLmust be the API's base, likehttp://minecraft:8110/api/v1, not the bare host and port. -
“token file: …”. The exporter can't read
WORLDAPI_TOKEN_FILE. Check the path inside the container and the file's permissions: the image runs as a non-root user. -
A targets file error. The file names the target and the key. Each target takes only
url,token,token_file, andplayers, and never bothtokenandtoken_file.
WorldAPI didn't answer GET /server.
- From the exporter's machine or container, run
curl http://your-server:8110/api/v1/server. It should return JSON. - If it can't connect, check the address, the port (WorldAPI's default is 8110), and the firewall between them. In Docker, use the server's service name, or
host.docker.internalfor a server on the host. - If WorldAPI answers 401, anonymous reads are off: give the exporter a token.
- If it answers slowly, raise
EXPORTER_TIMEOUTand Prometheus'scrape_timeouttogether.
They arrive a batch per scrape, so the first full set takes a minute or two. If they never come, look at minecraft_exporter_request_errors_total{endpoint="leaderboards"} and at WorldAPI's rate limit: another client on the same IP address may use up the anonymous limit. A token raises it.
- Check
minecraft_exporter_endpoint_allowed. An endpoint at0means the token lacks its permission. WorldAPI token says which one each needs. - After you add a permission to the token, wait up to 10 minutes: the exporter asks a closed endpoint again after that.
- Chat counts also need
events.chat: truein WorldAPI's config.
Event, chat, and console counters count from the exporter's start, and the first scrape only marks where to begin. Use rate() or increase() on them. Player statistics are the game's own lifetime counters and don't reset.
Each failed WorldAPI request counts here with its endpoint. Only that endpoint's metrics drop, and the rest of the scrape still arrives. Common causes: timeouts on a busy server, WorldAPI's rate limit (429), or a server restart. A refusal for a missing permission never counts here.
Each player gets their own series in a dozen metrics. On a big server set EXPORTER_PLAYERS=false: statistics add every player up, and the online players' details go away.
Still stuck? Open an issue with the exporter's log and the lines of /metrics that look wrong. Leave the token out.
For server owners
For developers