Skip to content

Troubleshooting

Jump to bottom
Ashutosh Das edited this page May 20, 2026 · 1 revision

Troubleshooting

This page covers the most common issues encountered when setting up or running Statfyr.

The API isn't responding

Symptoms: Requests to http://your-server:8080/api/health time out or are refused.

Check the following:

  1. Is the plugin enabled? Look for this in your console on startup: 
    [Statfyr] Statfyr 1.0.0-BETA enabled successfully.
    If you see an error instead, the plugin may have failed to load. Check for stack traces in the log.
  2. Is the port open? If your server is behind a firewall or a hosting panel, ensure port 8080 (or whichever port you configured) is open for inbound TCP connections.
  3. Is bind-address correct? If bind-address is set to 127.0.0.1, the API is only accessible from the same machine — not externally. Change it to 0.0.0.0 for public access.
  4. Is another process using the port? Check for port conflicts: 
    # Linux
ss -tlnp | grep 8080

# Windows
netstat -ano | findstr :8080
    If something else is using port 8080, change http.port in the config to a free port.

Getting 401 Unauthorized

Cause: API key authentication is enabled and the request is missing or using the wrong key.

Fix: Include the correct Authorization header:

Authorization: Bearer your-api-key

If you set the key via the STATFYR_API_KEY environment variable, make sure the variable is actually being passed to the server process.

Getting 403 Forbidden

Cause: IP whitelisting is enabled and your IP is not in the allowed-ips list.

Fix: Either add your IP to the whitelist:

security:
  allowed-ips:
    - "your.ip.address.here"

Or disable IP whitelisting if you don't need it:

security:
  enable-ip-whitelist: false

Getting 429 Too Many Requests

Cause: Your IP has exceeded the rate limit.

Fix: Wait for the rate limit window to reset (default: 60 seconds). If you're hitting limits legitimately (e.g. a high-frequency dashboard), increase the limit in the config:

security:
  rate-limit-requests: 300
  rate-limit-window-seconds: 60

Player returns 404 Not Found

Cause: The player name or UUID doesn't exist in the server's known player records.

Things to check:

  • Confirm the player has joined the server at least once
  • Check for typos in the player name (names are case-insensitive but must be correct)
  • Try using the player's UUID instead of their name

Stats look outdated or stale

Cause: The cache TTL is set high, so responses may be up to ttl-seconds old.

Fix: Lower the TTL for fresher data:

cache:
  ttl-seconds: 10
  refresh-seconds: 5

The API docs page isn't loading

Cause: API docs may be disabled in the config.

Fix: Ensure docs.enabled: true in config.yml, then reload:

/statfyr reload

Access docs at: http://your-server:8080/api/docs

HTTPS isn't working

Common causes and fixes:

Problem Fix
Keystore file not found Check keystore-path points to the correct location
Wrong keystore password Verify the password or set STATFYR_KEYSTORE_PASSWORD env var
https.enabled is false Set it to true and reload
Certificate not trusted Use a CA-signed cert, or accept the browser warning for self-signed

Config changes aren't taking effect

Cause: You edited the config but didn't reload.

Fix: Run /statfyr reload after any config change.

If reload doesn't help, do a full server restart — some changes (like port or bind address) may require it.

Still having issues?

Join the Statfyr Discord and describe your issue in the support channel. Include:

  • Your Statfyr version (/statfyr version)
  • Your Paper/server version
  • Any relevant error messages from the console
  • Your config.yml (remove your API key before sharing)

Next: Changelog

Clone this wiki locally