Documentation

Troubleshooting

Most production issues are a daemon that is not running, a listen-url the panel cannot open, or a truncated node token.

Node stays Offline

Symptom	What to check
Node stays Offline	journalctl -u flutter-daemon -e — token, node id, and --panel-url
Heartbeat OK, start/console fail	Panel cannot reach --listen-url. From the panel host: curl -sS http://NODE_IP:8080/health (or the trycloudflare.com URL)
flt_ token rejected	Copy the full token from the create screen or the Nodes clipboard button
flutter-node-configure is missing	Daemon install did not finish. Scroll up for the ubuntu-node error and re-run
rsync: mkdir .../packages/shared failed	Use the current install/ubuntu-node.sh from the repo (it creates that directory)
Docker is not running	On WSL: Docker Desktop → WSL integration. Then docker info inside Ubuntu
Port 8080 in use	Stop Windows npm run dev:daemon / any other Flutter daemon on this machine
Wrong machine	You ran ubuntu-24.04.sh on the game host. Wipe it; only ubuntu-node.sh or connect-home-node.sh belongs there
$'\r': command not found	sed -i 's/\r$//' install/*.sh then retry
Let's Encrypt refused	Hostname A record must resolve to this server. Certificates are not issued for raw IPs
Login page broken after update	Hard-refresh. Stale JS chunk hashes 404 until the tab reloads

bash

journalctl -u flutter-api -u flutter-web -u flutter-daemon -f
cd /opt/flutter && docker compose ps
curl -sS http://127.0.0.1:4000/api/v1/health

Does not uninstall Docker, Node.js, nginx, or cloudflared packages.

Daemon only (leaves a panel on the same machine alone):

bash

sudo bash install/wipe-local.sh --yes --daemon-only

Everything on this machine (panel + daemon + game data):

bash

sudo bash install/wipe-local.sh --yes

Flag	Meaning
--yes	Do not prompt (otherwise type wipe)
--daemon-only / --node-only	Remove the game-node daemon, tunnel, /opt/flutter-node, and game data
--keep-data	Leave /var/lib/flutter
--keep-user	Leave the flutter system user
--wipe-certs	Delete Let's Encrypt certs whose name contains flutter (full wipe only)
--keep-src	Leave /usr/local/src/flutter-panel