Troubleshooting

Start with the server console. Most setup issues leave a direct error in the plugin log, and the status plus diagnostics commands show whether the server is linked, which transport is active, and what the next repair step is.

What diagnostics tells you

Diagnostics is the fastest way to turn "the plugin does not work" into a specific cause. It can show whether the Agent is initialized, whether config is loaded and writable, whether the gateway client exists and is ready, whether the token is missing or invalid, whether the verification environment is enrolled, whether whitelist enforcement has a binding, whether backend relay is active on a proxy, and whether the configured API/gateway endpoints are reachable from the server.

Use the right command prefix

Paper, Spigot, Folia, Fabric, and NeoForge use /leavepulse.

Velocity uses /leavepulsevelocity.

BungeeCord and Waterfall use /leavepulsebungee.

Use the matching prefix for every command below. The same rule applies to whitelist and maintenance commands: Velocity uses /whitelistvelocity and /maintenancevelocity; BungeeCord/Waterfall use /whitelistbungee and /maintenancebungee.

First diagnostic bundle

Run these before editing config:

The export writes diagnostics/latest.json under the plugin config directory. Keep this file for support. It explains gateway state, token validity, token/server ID mismatch, enrollment, whitelist readiness, filesystem permissions, scheduler state, command registration, backend relay state, and API/gateway TCP reachability.

If support asks for deeper checks, run:

Safe mode is the default. Standard mode can run reversible probes such as config reload and temp-file write checks.

Gateway not connected

Symptom: the website shows the Agent as offline, or /leavepulse status does not show a healthy gateway transport.

Run:

Check the diagnostics messages and actionHint fields first. If gateway.ws_url, gateway.token, or server_id is missing, reconnect from the website with a fresh connect code. If endpoint reachability fails, fix DNS/firewall/proxy access to the configured API or gateway host.

Token missing or invalid

Symptom: diagnostics reports a missing token, malformed token, expired token, invalid claims, signature failure, or a server_id mismatch.

Run /leavepulse connect <code> again from the website setup flow. Do not manually copy a token from another server.

If a token was leaked, reconnect the server so a new token is issued.

Diagnostics can distinguish missing token, malformed token, expired token, invalid claims, signature verification failure, and server_id mismatch:

Server already linked

Symptom: the connect command warns that this runtime is already attached to another LeavePulse server.

If /leavepulse connect <code> warns that the plugin is already linked, verify that you are connecting the correct Minecraft server to the correct LeavePulse server page.

Only then run:

Whitelist not configured

Symptom: in-game whitelist commands work, but moderation decisions are not applied or the command says no whitelist is configured.

Open the website whitelist settings and confirm that the server or project has a whitelist binding. Then run:

/leavepulse reload
/leavepulse status
/leavepulse diagnostics suite leavepulse.whitelist

If in-game whitelist commands report that the whitelist is not configured, the plugin can reach the gateway but has no binding to apply.

Metrics not updating

Symptom: the Agent is installed, but player counts, events, or runtime fields stop changing on the website.

Run:

/leavepulse send
/leavepulse diagnostics suite leavepulse

Then check the website after a short delay. If no update appears, use diagnostics to verify server_id, gateway status, last send error, and outbound network access to the LeavePulse API host.

Backend metrics missing

Symptom: a proxy is connected, but backend/subserver metrics are absent or mapped to the wrong server.

Run diagnostics on the proxy process first, not on a backend:

Confirm that backend relay is enabled and that backend server names match the LeavePulse server records you expect. If a backend also runs its own Agent, connect that backend runtime to its own server record and do not reuse the proxy config.

Player cannot join

Symptom: a player is kicked, blocked, or restricted even though they expect access.

Check whether maintenance mode is enabled:

Check whether whitelist enforcement is kick or restrict, then review the player's application status. A player with pending, denied, or revision status should not be treated the same as an approved player.

Update check or download issues

Symptom: update status is stale, download fails, or an update is staged but not applied.

Run:

/leavepulse update status
/leavepulse update check
/leavepulse diagnostics export

Confirm that auto_update.enabled is true, the channel is correct, and the server can download from the configured update source. If automatic apply is disabled, restart or apply according to your platform's update policy.

If the first install download card is empty or does not show your platform, use Agent downloads to check the source order, channels, and fallback behavior.