Troubleshooting¶

Use this page when the UI and the swarm host disagree, or when a deployment does not become reachable.

Swarm host Does Not Appear In The UI¶

Checks:

1. Make sure the agent is running.
2. Make sure you started it with a valid --user-token.
3. Confirm the control-plane URL is correct.
4. Check the agent logs for registration errors.

Example:

./swarm-agent --name <HOST_NAME> --user-token <USER_TOKEN> --log-level DEBUG

If the host was previously registered and you want a fresh identity, run with --force-register or delete ~/.swarm_agent/identity.json.

The agent connects to https://swarmhosts.com by default. Use --server only for local development or a private control plane.

Swarm host Shows Offline¶

This usually means heartbeats stopped arriving.

Check:

• the agent process or systemd service is still running
• the swarm host can still reach the control plane
• the control plane URL has not changed

Systemd example:

sudo journalctl -u swarm-agent -n 200 --no-pager

Direct File Manager Path Does Not Work¶

The UI prefers a direct browser-to-swarm host gateway connection when possible.

Check:

• the swarm host gateway is enabled
• the gateway port is reachable
• the swarm host detail page shows the expected gateway URL and reachability state

If the direct path fails, Swarm Hosts may fall back to WebRTC when that path is available.

Deployment Stays In pending_deploy Or dispatched¶

Check:

1. The swarm host agent is still polling for tasks.
2. Docker is installed and the daemon is running.
3. The swarm host has enough CPU, memory, and ports.
4. The deployment logs show image-pull or startup errors.

Useful host commands:

docker ps -a
docker logs <CONTAINER_ID>

Container Starts But Players Cannot Connect¶

Check:

• the swarm host public IP is correct
• you are sharing the assigned host port from the UI, not the container's internal default port
• the firewall and router forward the required TCP or UDP protocol
• the deployment's Public Access badge and help link

If the detail page shows Can't connect? Need help?, open the linked Port Forwarding Basics guide.

File Manager Can Browse But Saves Fail¶

Check:

• the deployment is still accessible
• the persistent data directory exists under the swarm host --data-root
• the swarm host has free disk space
• the gateway token secret is correct if using the direct gateway path

Multiple Swarm hosts Behind One Public IP Conflict¶

If registration fails after you add a second swarm host behind the same router, check the configured port ranges. They must not overlap.

Example safe split:

host-a: 40000-40100
host-b: 40101-40200