coollabsio/coolify · error · Exception

Server OS type is not supported for automated installation…

Error message

Server OS type is not supported for automated installation. Please install Docker manually before continuing: <a target="_blank" class="underline" href="https://coolify.io/docs/installation#manually">documentation</a>.

What it means

InstallDocker action calls Server::validateOS(), which SSHes to the host, parses /etc/os-release ID=, and matches it against the SUPPORTED_OS groups (ubuntu/debian/raspbian/pop, centos/fedora/rhel/ol/rocky/amzn/almalinux, sles/opensuse-leap/opensuse-tumbleweed, arch, alpine — bootstrap/helpers/constants.php:87). If the ID matches no group, validateOS() returns false and the action throws, directing the user to install Docker manually.

Solutions

Install Docker Engine manually on the host (see the linked coolify.io/docs/installation#manually guide), then re-run validation — Coolify will detect the existing Docker.
Rebuild the server on a supported OS (Ubuntu/Debian, RHEL family, openSUSE, Arch, Alpine).
If the OS should be supported, SSH in and check /etc/os-release — fix the ID= line or detection inputs.
(Maintainer) extend SUPPORTED_OS and the corresponding install branch if the distro is genuinely supported.

Defensive patterns

Strategy: validation

Validate before calling

$os = $server->validateOS(); // requires working SSH; returns Stringable group or false
if ($os === false) {
    // route to manual-install guidance instead of dispatching InstallDocker
    return 'This OS is not auto-installable. Install Docker manually, then re-validate.';
}
InstallDocker::run($server);

Type guard

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

Try / catch

try {
    InstallDocker::run($server);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'Server OS type is not supported')) {
        // permanent condition — instruct manual install, do not retry
    } else {
        throw $e;
    }
}

Prevention

Provision servers on distros in SUPPORTED_OS (Debian/Ubuntu, RHEL family, openSUSE, Arch, Alpine).
Run server validation before triggering installs — it performs the same OS check earlier with clearer output.
Pre-install Docker in your base image so automated install is never needed.
Check /etc/os-release on unusual images before adding the server.

When it happens

Trigger: Running InstallDocker (or server validation with installation) on a host whose /etc/os-release ID is outside SUPPORTED_OS: nixos, gentoo, freebsd, or a custom/minimal image where os-release is missing or has a nonstandard ID= so the parsed $ID is null and nothing matches.

Common situations: Niche distros, BSD-based hosts, hardened/minimal images without /etc/os-release, LXC templates with customized os-release, someone assuming any Linux works because Docker itself supports more distros than Coolify's installer.

Related errors

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

Appendix: source

Thrown at app/Actions/Server/InstallDocker.php:18

<?php

namespace App\Actions\Server;

use App\Helpers\SslHelper;
use App\Models\Server;
use App\Models\StandaloneDocker;
use Lorisleiva\Actions\Concerns\AsAction;

class InstallDocker
{
    use AsAction;

    public function handle(Server $server)
    {
        $supported_os_type = $server->validateOS();
        if (! $supported_os_type) {
            throw new \Exception('Server OS type is not supported for automated installation. Please install Docker manually before continuing: <a target="_blank" class="underline" href="https://coolify.io/docs/installation#manually">documentation</a>.');
        }

        if (! $server->sslCertificates()->where('is_ca_certificate', true)->exists()) {
            $serverCert = SslHelper::generateSslCertificate(
                commonName: 'Coolify CA Certificate',
                serverId: $server->id,
                isCaCertificate: true,
                validityDays: 10 * 365
            );
            $caCertPath = config('constants.coolify.base_config_path').'/ssl/';

            $base64Cert = base64_encode($serverCert->ssl_certificate);

            $commands = collect([
                "mkdir -p $caCertPath",
                "chown -R 9999:root $caCertPath",
                "chmod -R 700 $caCertPath",
                "rm -rf $caCertPath/coolify-ca.crt",

View on GitHub (pinned to 70b9acc424)