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 People page.
Verify reachability — nc -vz your-host 25565 from another machine.

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, and chunk load.

BlueMap 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 BlueMap 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 Server → Backups. See Updating Beacon.

Still stuck?

Re-run beacon doctor — it flags template drift and missing config and often names the fix.
File an issue with beacon status --json output and the relevant beacon logs on GitHub.