Troubleshooting

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

If you still need help after these checks, use the Support Checklist to collect the account email, swarm host name, deployment or server ID, game, status/error, public reachability result, safe logs or screenshots, steps already tried, and whether the issue is blocking launch.

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.

For Minecraft, open the deployment detail page and use the Common fixes for this Minecraft deployment panel when it appears. It can retry a failed or stuck launch, start or restart an existing container when safe, prune unused Docker images, queue a supported agent update, copy a redacted support report from the diagnostics panel, and show why unsafe repairs are not available. Deployment details also keep a recent repair-attempt history, including queued, running, succeeded, failed, unavailable, and superseded outcomes when available, and the copied diagnostics include that redacted history for support.

Useful host commands:

docker ps -a
docker logs <CONTAINER_ID>

Container Runtime Storage Fills Up

The swarm host agent automatically runs docker image prune -a --force or podman image prune -a --force when the selected runtime storage reaches 80% usage. The cleanup removes images that are not used by any container and does not stop running deployments.

To trigger cleanup immediately, open the swarm host detail page, choose Operations, and select Prune unused images.

If the disk still fills after image pruning, check Docker/containerd or Podman storage, volumes, build cache, and the deployment data root separately. Image pruning does not remove runtime volumes or world data.

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
  • for Minecraft Java, the deployment's Minecraft protocol row shows a fresh post-deploy status proof, not a stale proof

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

Minecraft Helper Bots Do Not Start Or Stop

Open the deployment's Bots page and check the visible blocker first. A new session requires a running Minecraft Java deployment, a reachable Java status check, Authenticate with Mojang turned off, deployment manage access, and a clear deployment action queue. Builder and Miner are intentionally unavailable.

If a session is stuck, reconnecting unexpectedly, or has the wrong online count:

  1. choose Stop all bots;
  2. wait for each session to become Stopped, Failed, or Timed out;
  3. choose Clean up on every terminal session;
  4. confirm active, desired, and online bot counts return to zero; and
  5. confirm the Minecraft Java status check remains reachable.

Do not start duplicate sessions while an action is queued. If a bot remains online after cleanup, preserve the visible blocker, last reconcile time, event types, and sanitized artifact IDs, then use the Support Checklist. See Minecraft Helper Bots for status meanings and profile limits.

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