Troubleshooting

Where to look

Panel	docker compose logs panel
Agent	docker logs panel-agent on the node (or docker compose -f compose.agent.yml logs)
A server	its Console: the panel’s own notes start with [panel], installs with [job]
Port forwarding	the provider’s card on the node’s page: when it last applied, and its last error
Webhooks	the webhook’s deliveries, with the answer

A node stays offline

Check the agent’s log:

• Enrollment failed: the token is used up or older than 24 hours. Create a new one on the node’s page (New enrollment token), set AGENT_ENROLLMENT_TOKEN and recreate the agent.
• Connection to the panel lost: … again and again:
  • Can the node reach the panel? curl -I <AGENT_PANEL_URL> on the node.
  • Behind a reverse proxy: it must pass WebSockets.
  • The panel refuses another protocol version (protocol_mismatch): update the agent (Updates).
• The panel no longer accepts this node's identity: someone created a new enrollment token for the node. Set it as AGENT_ENROLLMENT_TOKEN and recreate the agent.

An install fails

The console shows the install’s output ([job] lines). Common causes:

• The image can’t be pulled: a private registry needs a login (Admin → Settings → Registries), and the node must reach the registry.
• Steam: the account must own the game; a Steam Guard prompt left unanswered for 5 minutes fails the job. See Steam accounts.

Fix the cause, then Reinstall.

A server doesn’t start, or stops by itself

The last console lines tell why:

Console	Meaning
[panel] The server uses … MB of its … MB disk limit. Delete files or raise the limit.	over the disk limit: it doesn’t start (or is stopped while running). Delete files, or raise the limit under Settings → Name and limits.
[panel] Server stopped (exit code 137).	killed: usually out of memory. Raise the memory limit, or lower the game’s own setting (Java’s -Xmx follows the limit at the next start).
[panel] Server stopped (exit code …).	the game ended on its own: its lines above say why

Players can’t connect

1. The address: the server page shows it, from the node’s public address and the server’s ports. Is it the address players use?
2. The server: is it running, and does the player count work? Then the game answers on the node.
3. Port forwarding: does the provider’s card show an error? Is the port forwarded with the right protocol (UDP for most Steam games)?
4. Firewalls: the node’s own firewall and the cloud’s firewall must let the ports in. Docker bypasses host firewalls like ufw for published ports, so a cloud firewall is the effective control.
5. From inside the LAN: some routers don’t forward a connection to their own public address back inside. Try the LAN address, or from outside.

SFTP refuses the login

• The user name is <email>.<server id>, exactly as on the Files tab.
• Two-factor accounts can’t use their password over SFTP: add an SSH key under Account → SSH keys.
• Permissions: members need files.sftp on the server.
• Blocked: after 10 failed logins, the address is blocked for 10 minutes.
• Off: SFTP can be switched off for the whole installation in Admin → Settings.

Email doesn’t arrive

Admin → Settings → Email → Send test mail names the server addresses it tried and why they failed. Check the host and port, the security mode (STARTTLS 587, TLS 465), and the sender address the mail server accepts.

Webhooks and notifications

• A webhook isn’t delivered: its deliveries show the answer, e.g. HTTP 400. Addresses in private networks are refused unless webhooks to the local network is on in Admin → Settings (on by default for homelabs).
• Push notifications: they need the panel on HTTPS. On iPhones, the panel must be added to the home screen (iOS 16.4 or newer). Send a test on the account page checks a device.