{"record":{"id":"fc822ce1580bb5b1","repo":"coollabsio/coolify","slug":"server-os-type-is-not-supported-for-automated-inst","errorCode":null,"errorMessage":"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>.","messagePattern":"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>\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"app/Actions/Server/InstallDocker.php","lineNumber":18,"sourceCode":"<?php\n\nnamespace App\\Actions\\Server;\n\nuse App\\Helpers\\SslHelper;\nuse App\\Models\\Server;\nuse App\\Models\\StandaloneDocker;\nuse Lorisleiva\\Actions\\Concerns\\AsAction;\n\nclass InstallDocker\n{\n    use AsAction;\n\n    public function handle(Server $server)\n    {\n        $supported_os_type = $server->validateOS();\n        if (! $supported_os_type) {\n            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>.');\n        }\n\n        if (! $server->sslCertificates()->where('is_ca_certificate', true)->exists()) {\n            $serverCert = SslHelper::generateSslCertificate(\n                commonName: 'Coolify CA Certificate',\n                serverId: $server->id,\n                isCaCertificate: true,\n                validityDays: 10 * 365\n            );\n            $caCertPath = config('constants.coolify.base_config_path').'/ssl/';\n\n            $base64Cert = base64_encode($serverCert->ssl_certificate);\n\n            $commands = collect([\n                \"mkdir -p $caCertPath\",\n                \"chown -R 9999:root $caCertPath\",\n                \"chmod -R 700 $caCertPath\",\n                \"rm -rf $caCertPath/coolify-ca.crt\",","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/coollabsio/coolify/blob/70b9acc42467278373e00de77abb40684e25b395/app/Actions/Server/InstallDocker.php#L1-L36","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"$os = $server->validateOS(); // requires working SSH; returns Stringable group or false\nif ($os === false) {\n    // route to manual-install guidance instead of dispatching InstallDocker\n    return 'This OS is not auto-installable. Install Docker manually, then re-validate.';\n}\nInstallDocker::run($server);","typeGuard":"function isAutoInstallableOs(\\App\\Models\\Server $server): bool\n{\n    return $server->validateOS() !== false;\n}","tryCatchPattern":"try {\n    InstallDocker::run($server);\n} catch (\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Server OS type is not supported')) {\n        // permanent condition — instruct manual install, do not retry\n    } else {\n        throw $e;\n    }\n}","preventionTips":["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."],"tags":["docker","os-detection","server-setup","ssh","installation"],"backgroundTag":"unsupported-operating-system","analyzedSha":"70b9acc42467278373e00de77abb40684e25b395","analyzedAt":"2026-08-17T01:41:01.313Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}