What causes "Server is not reachable. Please validate your configuration and connection. Check this documentation for further help. Error: {$sanitizedError} " in coollabsio/coolify?

Read the embedded 'Error:' text — it distinguishes auth failure from timeout/refused and points at the fix.

coollabsio/coolify · error · Exception

Server is not reachable. Please validate your configuration

Error message

Server is not reachable. Please validate your configuration and connection.<br>Check this <a target="_blank" class="text-black underline dark:text-white" href="https://coolify.io/docs/knowledge-base/server/openssh">documentation</a> for further help. <br><br><div class="text-error">Error: {$sanitizedError}</div>

What it means

ValidateServer ran Server::validateConnection(), which executes `ls /` over SSH (instant_remote_process) and catches any Throwable. On failure the raw SSH error message is sanitized with htmlspecialchars and embedded into this HTML error (with an openssh docs link), persisted to validation_logs, and thrown. The embedded 'Error: {...}' part names the actual SSH failure — authentication, timeout, connection refused, etc.

Source

Thrown at app/Actions/Server/ValidateServer.php:73

            if (in_array($status, ['off', 'archive', 'deleted'], true)) {
                $this->error = $status === 'deleted'
                    ? 'DigitalOcean droplet is deleted or no longer accessible. Relink this server before validating.'
                    : 'DigitalOcean droplet is '.($status ?? 'not running').'. Power it on before validating.';
                $server->update([
                    'validation_logs' => $this->error,
                ]);
                throw new \Exception($this->error);
            }
        }

        ['uptime' => $this->uptime, 'error' => $error] = $server->validateConnection();
        if (! $this->uptime) {
            $sanitizedError = htmlspecialchars($error ?? '', ENT_QUOTES, 'UTF-8');
            $this->error = 'Server is not reachable. Please validate your configuration and connection.<br>Check this <a target="_blank" class="text-black underline dark:text-white" href="https://coolify.io/docs/knowledge-base/server/openssh">documentation</a> for further help. <br><br><div class="text-error">Error: '.$sanitizedError.'</div>';
            $server->update([
                'validation_logs' => $this->error,
            ]);
            throw new \Exception($this->error);
        }
        $this->supported_os_type = $server->validateOS();
        if (! $this->supported_os_type) {
            $this->error = 'Server OS type is not supported. Please install Docker manually before continuing: <a target="_blank" class="text-black underline dark:text-white" href="https://docs.docker.com/engine/install/#server">documentation</a>.';
            $server->update([
                'validation_logs' => $this->error,
            ]);
            throw new \Exception($this->error);
        }

        $validationResult = $server->validatePrerequisites();
        if (! $validationResult['success']) {
            $missingCommands = implode(', ', $validationResult['missing']);
            $this->error = "Prerequisites ({$missingCommands}) are not installed. Please install them before continuing or use the validation with installation endpoint.";
            $server->update([
                'validation_logs' => $this->error,
            ]);
            throw new \Exception($this->error);

View on GitHub (pinned to 70b9acc424)

Solutions

Read the embedded 'Error:' text — it distinguishes auth failure from timeout/refused and points at the fix.
Verify IP, port and user in the server settings, then test manually from the Coolify host: ssh -p <port> <user>@<ip>.
Open the server firewall/security group for SSH from the Coolify instance.
Reinstall the team's public key in ~/.ssh/authorized_keys on the host and re-validate.

Defensive patterns

Strategy: try-catch

Validate before calling

['uptime' => $up, 'error' => $err] = $server->validateConnection();
if (! $up) {
    return 'SSH unreachable: '.$err; // fail fast with the raw reason
}
ValidateServer::run($server);

Try / catch

try {
    ValidateServer::run($server);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'Server is not reachable')) {
        // read the embedded Error: {...} — retry only for timeouts/transient network,
        // never for auth failures; the full message is also in validation_logs
    } else {
        throw $e;
    }
}

Prevention

Pre-verify SSH from the Coolify host: ssh -p <port> <user>@<ip> before adding the server.
Keep the team's public key installed and firewalls open to the Coolify instance IP.
Note that validation_logs stores the exact sanitized error — read it before retrying.
Distinguish auth errors (fix keys) from timeouts (fix network) — retrying auth failures is pointless.

When it happens

Trigger: Wrong IP/SSH port/username in server settings; missing or revoked authorized key; firewall or cloud security group blocking SSH; DNS pointing at the wrong host; server powered off; host key/SSH mux issues (validateConnection disables mux first, so mux is usually not the cause).

Common situations: Fresh server where the Coolify team key was never installed; elastic IP changed after reboot; security group not opened to the Coolify instance's IP; local network blocking outbound 22.

Related errors

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