coollabsio/coolify · error · Exception

Server OS type is not supported. Please install Docker manua

Error message

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>.

What it means

After connectivity succeeds, ValidateServer runs the same Server::validateOS() used by the installers: parse /etc/os-release ID= over SSH and require exactly one match in SUPPORTED_OS (ubuntu/debian/raspbian/pop, centos/fedora/rhel/ol/rocky/amzn/almalinux, sles/opensuse-*, arch, alpine). A false return throws this error (with the Docker install docs link), persists it to validation_logs, and stops validation before prerequisite/Docker checks.

Source

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

            }
        }

        ['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);
        }

        $this->docker_installed = $server->validateDockerEngine();
        $this->docker_compose_installed = $server->validateDockerCompose();
        if (! $this->docker_installed || ! $this->docker_compose_installed) {
            $this->error = 'Docker Engine is not installed. 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,

View on GitHub (pinned to 70b9acc424)

Solutions

Install Docker manually per the linked Docker docs, then re-run validation (Docker presence is checked separately).
Use a supported OS for automated management.
Check /etc/os-release on the host if you believe the distro is supported.

Defensive patterns

Strategy: validation

Validate before calling

if ($server->validateOS() === false) {
    return 'OS not supported. Install Docker manually, then re-validate.';
}
ValidateServer::run($server);

Type guard

function isSupportedOs(\App\Models\Server $server): bool
{
    return $server->validateOS() !== false;
}

Try / catch

try {
    ValidateServer::run($server);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'OS type is not supported')) {
        // permanent: manual Docker install or OS change required
    } else {
        throw $e;
    }
}

Prevention

Provision on distros listed in SUPPORTED_OS.
Pre-install Docker so validation passes on first attempt.
Inspect /etc/os-release when unsure — detection keys off the ID= line.

When it happens

Trigger: Validating a server whose distro ID is outside SUPPORTED_OS (nixos, gentoo, freebsd...) or whose /etc/os-release is missing/unparseable so $ID is null.

Common situations: Niche/minimal/BSD hosts, containers used as 'servers', customized OS images with a nonstandard ID= line.

Related errors

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