coollabsio/coolify · error · Exception

Docker Swarm is not initiated. Please join the server to a s

Error message

Docker Swarm is not initiated. Please join the server to a swarm before continuing.

What it means

Thrown by Server::validateDockerSwarm() (app/Models/Server.php:1613). The method SSHes to the server, runs `docker info|grep -i swarm`, takes the value after 'Swarm:' and throws when it equals 'inactive' — i.e. the remote Docker daemon is not in swarm mode. It is a precondition check before Coolify accepts the server for a SwarmDocker destination (which needs an overlay network, created afterwards via validateCoolifyNetwork(isSwarm: true)). The unreachable `return false` after the throw shows it was converted from a boolean API to a hard failure.

Source

Thrown at app/Models/Server.php:1613

            $this->settings->save();
            if ($throwError) {
                throw new \Exception('Server is not usable. Docker Compose is not installed.');
            }

            return false;
        }
        $this->settings->is_usable = true;
        $this->settings->save();

        return true;
    }

    public function validateDockerSwarm()
    {
        $swarmStatus = instant_remote_process(['docker info|grep -i swarm'], $this, false);
        $swarmStatus = str($swarmStatus)->trim()->after(':')->trim();
        if ($swarmStatus === 'inactive') {
            throw new \Exception('Docker Swarm is not initiated. Please join the server to a swarm before continuing.');

            return false;
        }
        $this->settings->is_usable = true;
        $this->settings->save();
        $this->validateCoolifyNetwork(isSwarm: true);

        return true;
    }

    public function dockerVersion(): ?string
    {
        return $this->settings?->docker_version;
    }

    public function rememberDockerVersion(?string $version): void
    {
        $this->settings->update([

View on GitHub (pinned to 70b9acc424)

Solutions

SSH into the target server and run `docker swarm init` (single-node) or `docker swarm join --token <token> <manager:2377>` to join an existing swarm, then re-run validation in Coolify
Verify with `docker info | grep -i swarm` that it now reports 'active' before retrying
If swarm was not intended, use a Standalone Docker destination instead of SwarmDocker so validateDockerSwarm is never invoked
If the check seems to pass unexpectedly, confirm SSH actually returns output — a silently failed command yields an empty string, not 'inactive'

Example fix

# on the target server, before validating in Coolify
docker info | grep -i swarm      # Swarm: inactive  -> error will throw
docker swarm init               # Swarm: active
docker info | grep -i swarm      # now passes validateDockerSwarm()

Defensive patterns

Strategy: validation

Validate before calling

$state = str(instant_remote_process(['docker info|grep -i swarm'], $server, false))->trim()->after(':')->trim();
if ($state->value() !== 'active') {
    // tell the user to run: docker swarm init (or docker swarm join ...)
    return back()->withErrors(['server' => 'Enable swarm mode on the host first.']);
}
$server->validateDockerSwarm();

Try / catch

try {
    $server->validateDockerSwarm();
} catch (\Exception $e) {
    // Message already says 'join the server to a swarm'; surface it and link to `docker swarm init` docs instead of showing a raw 500.
}

Prevention

Run `docker swarm init` before adding Swarm destinations
Verify with `docker info | grep -i swarm` from the Coolify host's SSH session
Use Standalone Docker destinations for non-swarm hosts

When it happens

Trigger: Calling $server->validateDockerSwarm() (directly or via server validation before adding/using a Swarm Docker destination) on a host where `docker info` reports 'Swarm: inactive' because `docker swarm init` / `docker swarm join` was never run.

Common situations: Adding a server intended for Swarm deployments without initializing swarm mode first; fresh Docker installs; hosts where swarm mode was left (`docker swarm leave`) or never configured; using the Swarm destination flow on a standalone-Docker host.

Related errors

AI-assisted analysis of coollabsio/coolify@70b9acc424 (2026-08-17). Data as JSON: /api/errors/45de057eee8aa76d. Report an issue: GitHub.