Skip to content

Troubleshooting

Pavel Erokhin edited this page Nov 9, 2026 · 3 revisions

Start with /metrics on the exporter: most answers show there.

The exporter doesn't start

  • “nothing to read: set WORLDAPI_URL, or EXPORTER_TARGETS for /probe”. Set at least one of them.
  • “should end in /api/v1”. WORLDAPI_URL must be the API's base, like http://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, and players, and never both token and token_file.

minecraft_up is 0

WorldAPI didn't answer GET /server.

  1. From the exporter's machine or container, run curl http://your-server:8110/api/v1/server. It should return JSON.
  2. 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.internal for a server on the host.
  3. If WorldAPI answers 401, anonymous reads are off: give the exporter a token.
  4. If it answers slowly, raise EXPORTER_TIMEOUT and Prometheus' scrape_timeout together.

Player statistics are missing

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.

Metrics behind a permission are missing

  1. Check minecraft_exporter_endpoint_allowed. An endpoint at 0 means the token lacks its permission. WorldAPI token says which one each needs.
  2. After you add a permission to the token, wait up to 10 minutes: the exporter asks a closed endpoint again after that.
  3. Chat counts also need events.chat: true in WorldAPI's config.

Counters start at zero

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.

minecraft_exporter_request_errors_total grows

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.

Many player series

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.

Clone this wiki locally