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.

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)

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.