Everything you need, in one place.

The plugin isn't running, or it isn't reachable on the address/port you gave the app.

1. Check the server console for [PulseConnect] API listening on :7070 after startup. If it's missing, the plugin didn't load — see Plugin doesn't load.
2. Confirm the address in the app matches your server's public IP or hostname. If you self-host, your public IP (not 192.168.x.x).
3. Confirm the port matches api.port in config.yml (default 7070).
4. Test the port from outside your network using canyouseeme.org or your phone on cellular data. If the port is closed, your forward isn't working.
5. If you're behind a managed Minecraft host, confirm they've opened that port for you. Many hosts only expose the Minecraft port by default.

Either the router rule isn't applying, or your ISP is using Carrier-Grade NAT (CGNAT) — common on mobile, rural, and cellular ISPs — which makes inbound connections impossible without a workaround.

1. In your router, confirm the rule: external port 7070 → internal IP of your server, internal port 7070, protocol TCP.
2. Make sure you're forwarding to the server's current internal IP — DHCP can change it. Set a static lease for the server in your router.
3. Compare your public IP at whatismyipaddress.com with the IP your router shows on its WAN interface. If they differ, you're behind CGNAT and standard port forwarding won't work.

• Ask your ISP for a public IPv4 address (sometimes free, sometimes a small monthly fee).
• Use a tunneling service: Tailscale Funnel, Cloudflare Tunnel, or a small VPS reverse proxy.
• Move the Minecraft server to a VPS provider that gives you a real public IP (DigitalOcean, Linode, Hetzner, etc.).

Almost always a network-side restriction, not the app. Some Wi-Fi networks (corporate, school, public guest) block non-standard ports outbound. Some cellular carriers throttle or block similarly. Or, if it works on Wi-Fi but not cellular, you might be using a local IP that only resolves on your home network.

1. If you used a 192.168.x.x address in the app, that only works on your home Wi-Fi. Use your public IP or hostname instead.
2. Test from cellular by toggling Wi-Fi off. If it fails, the Wi-Fi network is blocking outbound traffic to your port.
3. Try a non-default port like 8443 in api.port — many networks allow that range while blocking unusual ones.

iOS only prompts once. If you dismissed it or denied it, the app can't reach servers on your local Wi-Fi (only over the internet).

The app's connection-error screen has an Open Settings button that deep-links to the right place. Or manually: iOS Settings → PulsePanel → Local Network → On.

This only matters when connecting to a server on the same Wi-Fi network as your phone. Connecting to a remote server over the internet doesn't need Local Network permission.

Something on either side changed. The usual suspects, in order of likelihood:

• Dynamic IP changed (most common for self-hosters) — your home IP rotates, and the address saved in the app no longer points to your server. Check your current public IP and update the app.
• Router restarted — port-forward rules sometimes don't survive firmware updates or reboots. Verify the rule is still active.
• Plugin or server updated — check the server console for [PulseConnect] errors after startup.
• iOS or app updated — try fully quitting and relaunching the app. If still broken, sign out and sign back in.
• Token expired — by default JWTs expire after 24 hours. Sign in again.

If your IP rotates often, set up a dynamic DNS hostname (DuckDNS, No-IP, Cloudflare with a script) and point the app at the hostname instead of the raw IP.

The JAR is missing, in the wrong folder, incompatible with the server software, or has a corrupted config.yml.

1. Confirm PulseConnect.jar is in plugins/, not a subfolder.
2. Check the full server console output during startup. Look for any line containing PulseConnect — if the JAR is being seen, you'll get either a success line or an explicit error.
3. If you see a YAML parse error, your config.yml has bad indentation or unquoted special characters. Restore the default by deleting plugins/PulseConnect/config.yml and restarting the server — it'll regenerate.
4. Confirm Java version: PulseConnect requires Java 17 or newer. Run java -version on the server.
5. Confirm server software: Paper, Spigot, or Purpur on Minecraft 1.21+. Forge and Fabric aren't supported.

Something else is already listening on port 7070 (or whatever you set in api.port). Common culprits: another instance of the same plugin, a different admin plugin (ServerTap, AdminAPI, etc.), or a leftover process from a previous server crash.

1. Stop the server cleanly. If a plugin from a previous run is still holding the port, give it 30 seconds to release.
2. On Linux: sudo lsof -i :7070 shows what's using the port. Kill that process if it's stale.
3. If two plugins genuinely need different ports, change api.port in config.yml to something unused (e.g. 7080) and update your port forward + the app.

The plugin's SQLite database is being hit by multiple writers at once and locking up. This is rare in normal use but can happen on very busy servers, after a crash, or if another tool is reading plugins/PulseConnect/pulseconnect.db while the plugin is running.

1. Close any external SQLite browser, sqlite3 CLI session, or backup tool that's accessing the plugin's database.
2. Stop the server. Wait 10 seconds. Start it again.
3. If errors persist, the database may be partially corrupt. Stop the server, copy pulseconnect.db somewhere safe as a backup, then delete it. The plugin will recreate a fresh database on next startup. (You'll lose audit log history, ticket history, and accounts — re-add the admin account via config.yml.)

Username or password doesn't match what the plugin's database stored. Common reasons: trailing spaces from copy-paste, caps lock, or the credentials in config.yml were changed after first launch (those fields only matter on first launch — the database is the source of truth after that).

1. Type the username and password manually instead of pasting. Watch for caps lock and trailing spaces.
2. If you changed admin.username or admin.password in config.yml after the plugin's first run, those changes had no effect. Use whatever credentials existed at first launch.
3. If you've truly forgotten, see Forgot admin credentials below.

5 failed login attempts within 15 minutes triggers an automatic lockout (configurable). The lockout is keyed by username + IP, and resets on its own.

1. Wait 15 minutes (or whatever security.lockout-minutes is in config.yml) and try once more — this time with the correct credentials.
2. If you need to bypass it immediately, restarting the server clears the in-memory lockout state.

The owner password is BCrypt-hashed in the plugin's database and isn't recoverable. The clean reset path is to wipe the database and let the plugin recreate the account from config.yml.

1. Stop the server.
2. Edit plugins/PulseConnect/config.yml and set admin.username and admin.password to fresh values.
3. Delete (or move aside as backup) plugins/PulseConnect/pulseconnect.db.
4. Start the server. The plugin will create a new database and a new owner account from the values in config.yml.
5. Sign in with the new credentials in the app.

What you lose: audit log history, closed tickets, any flagged players, ban/mute history that's stored in the plugin (server-side bans in the vanilla banlist are unaffected).

Push delivery has several layers — any one of them can be off. Work through them in order.

1. iOS-level permission — Settings → PulsePanel → Notifications → confirm Allow Notifications is on.
2. App-level toggles — in the app, Settings → Notifications → confirm the categories you care about (tickets, server lag, etc.) are enabled.
3. Server has internet access — the plugin needs outbound HTTPS to deliver pushes. If your server is firewalled to local-only, push won't work. A quick curl https://www.google.com from the server confirms outbound is open.
4. Device is registered — open the app once on the device you want notifications on. The app registers its APNs token on each launch.
5. Trigger a test event — join the server yourself (player_join is an easy one to verify), or open and reply to a ticket in-game.

If all of the above check out and notifications still aren't arriving, send the symptom + your iOS version to support@pulsepanelapp.com.

Almost always iOS-side, not server-side. Apple intentionally batches and throttles pushes when the device is in low-power mode, on a constrained network, or has been idle for a while. The relay forwards within milliseconds — Apple's queue is what introduces delay.

• Disable Low Power Mode on the device.
• Open the PulsePanel app at least once a day — apps that haven't been opened in a while get more aggressively throttled.
• For tickets specifically, raising priority (tickets.manage + Set priority → high) marks the push as time-sensitive on iOS, which bypasses some throttling.

For genuinely real-time monitoring, the in-app live console and dashboard are sub-second; push is for awareness when you're not in the app.

The app authenticated but no data is flowing. Most often this means the server is still mid-startup, or there's a plugin error suppressing the data streams.

1. Wait 20-30 seconds, then pull-to-refresh the dashboard.
2. Check the server console for any [PulseConnect] error lines around the time you signed in.
3. Force quit the app (swipe up from app switcher) and reopen it.
4. If the dashboard fills in but specific tabs (Console, Players, etc.) are empty, that points to a permission issue — sign out and back in to refresh your token.

The plugin uses optimistic locking on file writes. If the file changed on disk between when you opened it in the app and when you tried to save, the plugin returns a conflict instead of overwriting blindly.

1. Tap the file again to reload the latest version.
2. Re-apply your edits to the fresh content.
3. Save again.

This usually happens when something else (a plugin auto-rewrite, a separate SSH session, or another admin) modified the same file. The conflict is protecting your edits — the file would have lost data otherwise.

HTTP requests work but the live console / chat / events don't stream. Reverse proxies often need explicit WebSocket upgrade headers, and Cloudflare's free tier will sometimes interfere with long-lived WebSocket connections.

location /api/v1/ws {
  proxy_pass http://localhost:7070;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 86400;
}

Caddy handles WebSocket upgrades automatically. A simple reverse_proxy localhost:7070 works for both REST and WebSocket — no extra config needed.

Cloudflare's free plan supports WebSockets, but you may need to enable it explicitly under Network → WebSockets. If you're seeing intermittent disconnects, also check your Page Rules aren't caching the API path.