Swarm Hosts / Guides

Troubleshooting

Use this page when a host goes offline, a server will not start, or players cannot connect.

For an installed Linux agent, start with Linux Agent Recovery. It helps you check the service and identify common errors without sharing credentials or full system logs.

If you still need help after these checks, use the Support Checklist to collect the account email, swarm host name, Swarm Server 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. For a new host, use the current installer and a fresh one-use enrollment code from Profile → Connect a host. Codes expire after 15 minutes; personal API tokens and legacy account tokens cannot enroll a host.
  3. For an existing host, restart the agent with its saved identity and original service configuration. It does not need a new enrollment code to reconnect.
  4. Check the safe registration-error categories in the agent recovery guide.

For a manual first run, the enrollment code is passed through the existing --user-token option:

./swarm-agent --name <HOST_NAME> --user-token <ENROLLMENT_CODE>

Do not delete the saved identity or use --force-register to fix an offline host. That enrolls a new host identity and does not repair the existing host's server records. Follow the Linux recovery guide or Windows agent guide before replacing an identity.

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

For systemd, use the service-property and fixed event-category checks in the Linux recovery guide; do not copy unrestricted journal output.

Direct File Manager Path Does Not Work

The file manager tries an authorized browser-to-host connection when available.

Check:

  • the agent is online and its file gateway reports ready under Swarm Host → Overview → Platform capabilities
  • the browser can reach the host on the selected connection path
  • the file manager's connection status and safe error message

If the direct path fails, WebRTC may provide another connection path. Refresh the page to create a new authorized session after reconnecting the agent. Do not change or copy gateway credentials as a troubleshooting shortcut.

Updated hosts also support browsing and reading through your authenticated Swarm Hosts connection. This path stays responsive while logs are collected. If File Manager keeps waiting for queued actions, check that the host agent is up to date. Restore and migration operations can still temporarily hold file access while server data changes.

Swarm Server Stays In pending_deploy Or dispatched

Check:

  1. The swarm host agent is still polling for tasks.
  2. The selected container runtime is ready and accessible to the agent.
  3. The swarm host has enough CPU, memory, and ports.
  4. The Swarm Server logs show image-pull or startup errors.

For Minecraft, open the Swarm Server detail page and use the Common fixes for this Minecraft Swarm Server 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. Swarm Server 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.

The Help → Diagnose Server check also distinguishes free disk bytes from filesystem file-entry capacity on current Linux agents. A disk can have free bytes but still be unable to create files when its inode capacity is exhausted. The check is read-only and time-bounded; Windows and filesystems without inode counters show Not Applicable instead of estimating a value. If it reports low file capacity, remove unnecessary small files or expand the data filesystem, then rerun diagnostics before starting the server.

Prefer Help → Run diagnostics and Copy support report before collecting host logs. A successful runtime or port check does not prove that the game has finished starting or that a player can join; follow the selected game's guide for its readiness checks.

Server Action Shows Outcome unknown

Outcome unknown means the browser did not receive a matching task receipt. The server may still have accepted the action, so do not change the fields and submit a new request.

  1. Select Retry same request. This asks for the saved request's receipt; it does not queue another copy of the action.
  2. If the receipt is recovered, open View task details and wait for a terminal result. Receipt recovery confirms queuing, not successful execution.
  3. If the receipt remains unknown, use View action history or open Tasks, filter by the affected Swarm Server, and inspect recent running, complete, partial, and failed work.
  4. If the tab reports that saved-request recovery is unavailable, keep the form locked and use history to establish the outcome. Browser storage that was cleared or lost cannot reconstruct the original request.

Treat changed action fields as a new intent. Submit them only after you have resolved the earlier action's status. See Server Actions for the receipt and execution boundary.

Combined Minecraft Change Stops At A Later Stage

A combined review can admit several ordered stages, and acceptance is not completion. Open the affected Swarm Server and check Activity & Logs, backup history, and Content history before submitting another change.

  • If the first safety backup fails, the settings, version, and content work does not start. Resolve the displayed backup or host problem, then review the current drafts again.
  • If the settings and version deployment fails or has an uncertain result, content does not start. Check the current server status, image and version details, and deployment logs before deciding whether to retry or make a new plan.
  • If content is cancelled before files changed, the attached revision or current server state no longer matched the review. Reload the page, select Review together, and inspect the new plan.
  • If content fails after file work begins, open Content history and read the recovery result. When recovery succeeded, verify the server files and game behavior before making another change. When recovery failed, stop further changes and inspect the linked content backup. A backup marked Available is an archive record, not proof that a restore or game startup will succeed.
  • If the browser shows Outcome unknown, select Retry this exact request without changing the drafts. If the saved request is unavailable, use the histories to determine whether work was admitted before creating a new review.

Earlier completed stages are not automatically rolled back when a later stage fails. Confirm the server's current settings, version, content revision, status, and logs before taking the next action. If no usable recovery point appears, keep both histories and use the Support Checklist.

Maintenance Campaign Stops Or Fails

Open Swarm Servers, then Restart campaigns, Backup campaigns, or Version campaigns, and open the affected campaign. The campaign page shows the canary, each member's state, and a short failure reason when one is available.

  • If the canary fails, the remaining pending servers are skipped.
  • If a later member fails, other pending members are skipped, while restarts or backups already admitted continue to a terminal result.
  • Skipped means stop-on-failure prevented that member from starting. It is not evidence that the server itself failed.
  • For a failed restart, open the linked Swarm Server and check its current status and Activity & Logs before restarting it separately.
  • For a failed backup, open the linked Swarm Server's Files & Backups view. Resolve an unavailable swarm host, unsupported backup capability, another queued action, or the displayed backup error before reviewing a new campaign.

A backup campaign member marked successful has a local backup whose status is Available. This is not a completed restore test or a guarantee of recoverability. Inspect the restore point and use your normal restore-testing process before relying on it for recovery.

For a managed-version campaign, read each member's stage:

  • Backup accepted or Backup running means the member has not started its managed-version deployment.
  • Deploy accepted or Deploy running means the member's backup reached Available and its deployment operation is still in progress.
  • Failed means the backup or deployment operation reported a terminal failure.
  • Indeterminate means Swarm Hosts cannot safely determine the operation's result. Do not queue another version change for that server until support has reviewed the campaign and operation history.
  • Skipped means stop-on-failure prevented that member's work from being admitted.

A changed managed target, server configuration, content compatibility, access, another queued action, or another active restart, backup, or version campaign can stop admission. Resolve the displayed condition, wait for the existing campaign to close, and create a new review from current state. Swarm Hosts does not automatically retry or roll back a version campaign.

For a member whose backup is shown as Available, open the member's linked Swarm Server and go to Files & Backups to inspect that member's backup. Available means the local archive completed; it does not prove restore success, off-host durability, Minecraft playability, or recoverability. Also check Activity & Logs and the server's current status before choosing a next action. If a member is indeterminate, its operation is unavailable, or no backup is shown for that member, avoid further version changes and contact support with the campaign and operation history.

Swarm Host Shows Overallocated Or High Whole-Computer Pressure

These warnings describe different resource layers:

  • Overallocated means committed Swarm Server CPU or memory limits exceed the host's effective delegated budget. This can happen when the agent later reports less hardware. New launches, restores, and failover placement are blocked on that host until you restore the reported capacity, reduce or move existing Swarm Server commitments, or raise the allocation within detected capacity.
  • Whole-computer pressure is high means current physical CPU or memory use is at least 90%. Other desktop or server applications count toward this warning. In explicit All or Custom mode, pressure does not silently change the committed Swarm budget, so reduce either the allocation or the competing host workload when performance is poor.

The owner can review Swarm Host → Operations → Capacity → Swarm resource allocation. An allocation cannot be saved below current commitments, and explicit allocation cannot be combined with Allow over commit. Automatic restores the legacy 10% reserve and live-usage-aware placement behavior.

Windows Host Says Docker Desktop Is Not Running After Reboot

This message does not necessarily mean the Swarm Hosts agent or Docker's Windows service failed. Docker Desktop has two relevant layers:

  • com.docker.service is the privileged Windows backend. The Swarm Hosts agent configures it for automatic startup, starts it when needed, and repairs it if Docker Desktop resets it to manual startup.
  • The Docker Desktop application and its Linux engine belong to an interactive Windows user session. Windows cannot make that Linux engine ready before the configured user signs in.

After a Windows reboot:

  1. Sign in as the Windows user used when the Swarm Hosts agent was installed.
  2. Wait for Docker Desktop to start. If necessary, open it manually.
  3. Confirm Docker Desktop is using Linux containers.
  4. Run docker info in PowerShell and wait until it returns server information.
  5. Return to the Swarm Host Operations page and refresh storage analysis.

Rerun the current Windows bootstrap installer if Docker Desktop does not start automatically after sign-in. It repairs the automatic service and sign-in-task configuration without deleting the Swarm Host identity or Swarm Server data.

Filesystem and Swarm Server data analysis remain available before sign-in, but Docker image, container, and volume totals do not. A Windows machine that must host containers without any user sign-in needs a supported service-native Linux-container engine because Docker Desktop normally starts its engine after the configured Windows user signs in. For installer and service diagnostics, continue with the Windows Agent guide.

Container Runtime Storage Fills Up

By default, the agent prunes unused container images when the filesystem holding the selected runtime's storage reaches 80% usage. This threshold can be changed in the agent configuration. Cleanup removes images that are not used by any container and does not stop running Swarm Servers. Pruned images may need to be downloaded again on a later launch.

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 Swarm Server data root separately. Image pruning does not remove runtime volumes or world data.

Game Or Backup Storage Shows Prior Known-Good Or Legacy Fallback

Open Swarm Host → Operations → Game and backup drives and read the effective source before changing anything:

  • Prior known-good locations active means the newest managed selection or local drive failed boot validation. The agent is still using the last validated game and backup locations. Restore the selected drive or mount, confirm it is writable, and restart the agent.
  • Legacy fallback means neither managed configuration was usable. The agent is using --data-root, SWARM_PRIMARY_BACKUP_DIR, and SWARM_REPLICA_DIR instead.
  • Restart required means the agent saved the desired locations, but a heartbeat has not yet confirmed that all runtime subsystems restarted on them.

Do not hand-edit or copy storage-locations.json, loosen its permissions, or move game/backup data as a troubleshooting shortcut. The workflow never migrates or adopts data. Linux operators should use the metadata-only checks in Linux Agent Recovery. Windows operators should use the protected-ACL checks in the Windows agent guide.

Container Starts But Players Cannot Connect

Check:

  • you are sharing the player address and assigned port shown in the UI
  • if using a relay, its connection status is healthy
  • for direct access, the host public IP is correct and the firewall and router allow the assigned port with the required TCP or UDP protocol
  • the Swarm Server's Public reachability result and connection-help link
  • for Minecraft Java, the Swarm Server's Minecraft protocol row shows a fresh successful status check from after the latest launch

Public reachability checks and game-protocol checks measure different things. A reachable relay or port does not guarantee game readiness or discovery in the game's server browser. Confirm a real game-client connection after startup. See Port Forwarding Basics for direct connections.

Minecraft Helper Bots Do Not Start Or Stop

Open the Swarm Server's Bots page and check the visible blocker first. A new session requires a running Minecraft Java Swarm Server, a reachable Java status check, Authenticate with Mojang turned off, Swarm Server manage access, and a clear Swarm Server 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:

  • your account has file write access to this Swarm Server; a viewer can browse without being able to save
  • the agent is online and no conflicting server action is pending
  • Help → Run diagnostics reports a writable data directory with free disk space and file capacity
  • the file manager reports an active connection and a fresh file-operation result

If a backup or another operation is using the files, the editor shows Waiting to save and retries for up to five minutes. Stop waiting keeps your draft and lets you save again later. You can also Download draft. Leave the editor open while waiting; backups and restore safety checks still protect your server files. Opening files and refreshing folders also wait through temporary contention; close the editor to cancel a waiting file read.

If the file changed since you opened it, download your draft before choosing Reload latest file. An interrupted save checks the current file before reporting success. When the result cannot be verified, the editor keeps your draft and requires a fresh read before saving again.

After reconnecting the agent, refresh the file manager and retry once. If saving still fails, copy the safe error and a private support report. Do not paste gateway tokens or change their secrets.

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

Swarm Zone backup sync is degraded

Check each peer on the Swarm Zone and Swarm Host pages. A usable pair must report a fresh private RFC 1918 address and a ready file gateway. A peer missing the base private-LAN capability must be updated before retrying. Older agents that already support encrypted private-LAN archives remain compatible: they use a full LAN copy instead of content-defined chunks. Zone backups never fall back through the relay or control plane.

As the host owner, open Swarm Host → Overview → Platform capabilities and copy the values shown for LAN backup replication, LAN replication capability, and LAN backup gateway port. The last value is the exact TCP port to test. If the capability or port says Not reported, update or restart the agent and wait for a fresh heartbeat instead of substituting a game port.

From the target host, test TCP reachability to the source's reported private address and the file-gateway port configured for that agent. Allow that port only between zone peers. Also verify that the archive is no larger than the default 64 GiB limit and that the LAN does not stall for the 120-second read timeout. If transfers succeed but disk use is higher than expected, the peer filesystem may not support hard-links; copy fallback stores another full archive and adds write I/O. Current peers also retain compressed binary chunks for later snapshots. The first snapshot transfers all chunks, and games that rewrite database, region, or compressed files may show less reuse than games with localized file changes.

Automatic Swarm Zone failover did not start

Start on the zone page. Automatic failover must be enabled, and the zone must have at least three connected hosts. Two peers need a healthy, fresh heartbeat, a private LAN address, and current failover-witness support. A reachable vote from either peer blocks recovery; fewer than two eligible unreachable votes also blocks it.

If a host says Witness probe is unavailable, install iputils-ping on Linux or restore the built-in Windows PING.EXE, then restart the agent and wait for a fresh heartbeat. An operational probe error also makes that host ineligible to witness until a later heartbeat reports successful probe execution. A peer reported as unreachable without a probe error is expected evidence during an outage and does not make the witnessing host unhealthy.

Then check the affected Swarm Server. It needs 3-copy protection, a recent successful backup within the zone's maximum backup age, and two verified peer copies. At least one surviving host must accept automatic failover restores and have enough delegated CPU, memory, and storage capacity.

The failure grace starts when the source heartbeat becomes stale. Eligibility begins at the selected boundary. Automatic recovery then waits for the original agent to confirm that its game servers are stopped with automatic restart disabled. Missing heartbeats, LAN votes, and a disabled relay route do not prove that the source stopped writing.

If the original host cannot respond, power it off or otherwise exclude its game processes, then open its Operations → Maintenance page and review Recover from backups with reviewed risk. Only the owner can accept this manual risk. Taking over without verified exclusion can create two divergent worlds and lose saves. Recovery requires a fresh, eligible replacement host owned by the same owner.

A returned source host remains fenced

This is expected after a successful automatic, manual, or retried failover. The fence prevents the old copy from starting beside its replacement. Confirm that the recovered Swarm Server is healthy and that its backup restore point is the one you expect. Wait until the original agent confirms exclusion of all source servers; upgrade an older agent if it cannot provide this confirmation. Then choose Return host to service on the zone page or the host's Operations → Maintenance page. Only the owner can return the host to scheduling. The old source server IDs remain blocked, including after agent or host restarts.