Troubleshooting

Start every diagnosis with the CLI's health probe — it's stricter than docker compose ps and tells you which layer is unhappy:

beacon status
beacon doctor

Then tail the relevant service:

beacon logs minecraft     # first boot / world generation
beacon logs admin-rpc     # RCON, Docker socket, backups, lifecycle
beacon logs web           # dashboard boot
beacon logs tailscale     # or: beacon logs caddy — ingress

Install & deploy

beacon: command not found — ~/.local/bin isn't on PATH. Run export PATH="$HOME/.local/bin:$PATH" (add it to your shell profile).
Installer fails: Docker / Node missing — the CLI needs Docker and Node.js 20+ on the host. Install both and rerun the installer.
manifest unknown on pull — BEACON_VERSION points at a tag that was never published. Set it to an exact release (no v prefix); see the changelog for valid versions.
!reset / overlay parse error — Docker Compose is older than 2.24. Upgrade Compose.

I missed the admin claim URL

The one-time claim link is printed once. Rotate and reopen it:

beacon restart
beacon logs admin-rpc      # open the latest ADMIN CLAIM LINK

A restart rotates any previous unclaimed token.

Players can't connect to Minecraft

Firewall — the host (and any cloud firewall) must allow inbound 25565/tcp. See Ports & Access.
Cloudflare proxy — if you put the address behind Cloudflare, set the DNS record to DNS only (gray cloud). The orange-cloud proxy drops raw TCP. This is the most common custom-address failure.
Not allowlisted — Beacon enforces the allowlist. Add the player on the dashboard's Players page.
Verify reachability — nc -vz your-host 25565 from another machine.

Players can join but voice chat is silent

Voice runs over UDP, on a different port from the game — joining proves nothing about voice.

Open the UDP port — 24454/udp (MC_VOICE_HOST_PORT) must be allowed on the host firewall and the cloud security group / router. Run beacon firewall --apply --yes, then add the matching cloud rule. This is the cause the vast majority of the time.
Missing the client mod — the player needs Simple Voice Chat for the same Minecraft version. The Beacon launcher installs it automatically; other launchers get it from the install guide.
Wrong loader — the toggle is disabled on vanilla. Switch to Paper or a mod loader on Server → Settings. See Voice Chat.
Groups blocked for non-ops — Simple Voice Chat grants voicechat.groups to everyone by default, but LuckPerms or another permission manager can deny it. Grant that node to the default group if open groups only work for ops.

I can't reach the dashboard

Tailscale mode — your own device must be signed into the same tailnet; check the node in the Tailscale admin console. beacon logs tailscale.
Custom-domain mode — on first boot Caddy returns 502 for 30–60s while it gets a certificate; that's normal. If it persists, confirm ports 80/443 are open and the A record is correct (DNS only on Cloudflare). beacon logs caddy.

The server is laggy or keeps dying

Out of memory — if the JVM is being killed, the host is short on RAM. beacon up warns when a host's beacons over-commit its memory; raise the VPS RAM or lower MC_MEMORY, then beacon restart. Swap won't rescue a JVM heap — see sizing the server.
Check the metrics — the dashboard's Server → Performance page shows TPS, memory, CPU, and chunk load, plus an Optimization tips panel that reads your config and flags the likely culprits.

CPU looks pinned but TPS is fine

The Performance page reports all-cores CPU: 100% is one core, not the whole box. On a 4-core host a healthy server can sit at ~150–250% and that's normal — the panel scales the chart to your core count and only flags red near total host capacity. With TPS locked at 20, a high number alone isn't a problem.

It only becomes a problem when the box saturates (near 100% of all cores). Minecraft's main tick runs on a single thread, so a saturated host starves it — usually worldgen as players explore, a busy plugin, or GC on an oversized heap.

Input lag / stutter even though TPS reads 20

TPS is a one-minute average, so it hides brief stalls. The thing players feel is a few individual ticks blowing past the 50 ms budget. Look at worst tick on the Performance page's tick panel (the faint upper line) — if the average is ~5 ms but the worst tick spikes to hundreds of ms, that's your stutter.

Profile it with spark. This is the only way to attribute CPU precisely, and the Performance page's CPU profiler runs a short one in a click. How spark is sourced depends on the loader: Paper / Purpur bundle it from 1.21+ (the /spark command just works — no install), Folia / older Paper need the spark plugin (it isn't on Modrinth — get it from spark.lucko.me), and on a mod loader the profiler card adds spark to your loadout for you. For a deeper capture, run /spark profiler --timeout 120 in-game and open the report, or /spark gc for pause times — it names the exact plugin / GC / worldgen split.
Right-size the heap. A heap far larger than you need (e.g. 12G for a few players) mostly lengthens GC pauses. A social Paper server is happy at 4–6G; lower MC_MEMORY and beacon restart.
Trim simulation distance first, then view distance, on Server → Settings.
Reserve CPU on a small/shared host. The live-map renderer runs in admin-rpc and shares the same cores; a render pass can stall the game. Set MC_CPU_LIMIT (cores) to cap the Minecraft container — see Configuration.

The live map won't render

Vantage needs to understand each Minecraft version's chunk format. After a brand-new Minecraft release, the map can show a world-load-failed banner until Vantage catches up. Pin a supported MC_VERSION until then; the map status banner explains the state.

Upgrade failed

A failed health gate triggers an automatic rollback to the previous version and compose files. If you need the world rolled back too, restore a pre-upgrade snapshot from Snapshots. See Updating Beacon.

Still stuck?

Re-run beacon doctor — it flags template drift and missing config and often names the fix.
Send beacon status --json output and the relevant beacon logs to admin@beacon-mc.io.

On this page