Troubleshooting

Note

This plugin hasn’t been approved by Modrinth yet, so you can’t download it from Modrinth right now.

Start with the server console. HMTAPI logs a warning for every config problem, every ignored endpoint and every failed request. The answer is usually there.

HMTAPI does not enable

Cause	Fix
PlaceholderAPI is missing or not enabled	Install PlaceholderAPI — it is a hard requirement
Server is not Paper, or is older than 26.3	Use Paper 26.3 or newer
Java is older than 25	Update to Java 25
/hmtapi is missing from plugin.yml	Reinstall a fresh jar

The console prints the specific reason, for example:

[HMTAPI] The '/hmtapi' command is missing from plugin.yml, disabling HMTAPI.

HMTAPI disables itself on start

[HMTAPI] Could not start the HTTP API on 0.0.0.0:4567. Please check the 'port' and 'bind_address' settings in config.yml.

The port is already taken or the address does not exist on this machine. See Connection refused below.

Connection refused

Nothing answers on the port. Check in this order:

1. Is the address right? bind_address must exist on the machine. 0.0.0.0 listens everywhere, 127.0.0.1 only locally.
2. Is the port free? Another plugin or service may be using it. Common conflicts: 25565 (Minecraft), your panel, your proxy.
3. Did you restart? bind_address and port only apply on restart, not on /hmtapi reload.
4. Is a firewall in the way? See Security.
5. Are you testing from the right machine? With bind_address: 127.0.0.1, another machine cannot reach it at all.
6. Was it working before? Look for Restart the server to apply it in the console — an earlier config change is waiting for a restart.

A config change had no effect

Setting	Needs
bind_address, port	Server restart
Everything else	/hmtapi reload

Also check the console for a warning about the value. An invalid value is ignored in favour of the default:

[HMTAPI] Invalid port '70000' in config.yml, it must be between 1 and 65535. Falling back to 4567.
[HMTAPI] Unknown time zone 'Mars/Olympus' in config.yml, falling back to UTC.
[HMTAPI] Invalid date format 'yyyy-QQQQQQ-dd' in config.yml, falling back to 'yyyy/MM/dd HH:mm:ss'.

HMTAPI never crashes your server over a bad config value. It logs, falls back to the default and keeps serving.

{"error": "endpoints not found."}

There is no endpoints section in your config, or you forgot to reload. Check the indentation — YAML is whitespace-sensitive, and endpoints: must sit at the left margin.

{"error": "Endpoint 'xyz' not found."}

No endpoint called xyz exists. Check that:

• the name in the URL matches the config exactly — names are case-sensitive
• the endpoint survived a reload
• the endpoint name uses only letters, digits, _ and -, and is at most 64 characters

{"error": "endpoints.xyz.object not found."}

That endpoint has no object section. It must be nested under the endpoint and must be a map:

endpoints:
  xyz: # endpoint name
    require_player: true
    object: # must be present
      key: "value"

An empty object: is valid and returns {}, but a missing object is an error.

{"error": "Endpoint 'xyz' requires a player name: ..."}

You requested an endpoint with require_player: true without a player name. Add one:

curl http://localhost:4567/api/xyz/Notch

Or set require_player: false if it is a server-wide endpoint.

404 with a list of routes

The URL does not match /api/{endpoint}, /api/{endpoint}/{username} or /favicon.ico. Check for typos, extra path segments, and spaces in player names.

503 — timed out

The server was too busy to answer within request_timeout_seconds. See Performance. Short version: raise the timeout, use fewer placeholders, or check whether your server is lagging for unrelated reasons.

500 — failed to collect data

Something threw an error while building the response, usually a third-party plugin resolving a placeholder. The console has the full stack trace and names the plugin. Remove placeholders from that endpoint one at a time to find it.

A placeholder comes back as %something%

The placeholder is not being resolved. Check that:

• PlaceholderAPI is installed and enabled
• the plugin providing the placeholder is installed and working
• you wrote {papi:%the_placeholder%} with both % signs
• the placeholder needs a player and you are using it on a require_player: false endpoint

{papi:%vault_eco_balance%} on a server-wide endpoint resolves without a player and has no balance to report. Move it to a player endpoint.

Dates look wrong

Adjust time_zone and date_format in the config, then reload. See Configuration.

A player who never joined has no date

That is expected. HMTAPI shows never_seen_value (never by default) for players with no login. See Placeholders.

The JSON looks broken or a value is cut off

If you edited config.yml by hand, check the quoting. Values containing :, #, a leading % or a leading * should be quoted:

object:
  rate: "50%"
  url: "https://example.com"
  note: "value: with colon"

Checking things yourself

# Full response with headers
curl -i http://localhost:4567/api/global

# Status code only
curl -o /dev/null -w "%{http_code}\n" http://localhost:4567/api/global

# Health check
curl -I http://localhost:4567/api/global

# From another machine on the network
curl http://<server-ip>:4567/api/global

Still stuck?

1. Read the console output from the moment you started the server.
2. Run /hmtapi reload and watch what it logs.
3. Test with a minimal endpoint containing only one value, e.g. name: "{username}".
4. Add your placeholders back one at a time.

Next steps

• Status codes — full reference of every response
• Configuration — every setting