{"record":{"id":"cbdf8a87985f7f30","repo":"coollabsio/coolify","slug":"server-os-type-is-not-supported-please-install-do","errorCode":null,"errorMessage":"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>.","messagePattern":"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>\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"app/Actions/Server/ValidateServer.php","lineNumber":81,"sourceCode":"            }\n        }\n\n        ['uptime' => $this->uptime, 'error' => $error] = $server->validateConnection();\n        if (! $this->uptime) {\n            $sanitizedError = htmlspecialchars($error ?? '', ENT_QUOTES, 'UTF-8');\n            $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>';\n            $server->update([\n                'validation_logs' => $this->error,\n            ]);\n            throw new \\Exception($this->error);\n        }\n        $this->supported_os_type = $server->validateOS();\n        if (! $this->supported_os_type) {\n            $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>.';\n            $server->update([\n                'validation_logs' => $this->error,\n            ]);\n            throw new \\Exception($this->error);\n        }\n\n        $validationResult = $server->validatePrerequisites();\n        if (! $validationResult['success']) {\n            $missingCommands = implode(', ', $validationResult['missing']);\n            $this->error = \"Prerequisites ({$missingCommands}) are not installed. Please install them before continuing or use the validation with installation endpoint.\";\n            $server->update([\n                'validation_logs' => $this->error,\n            ]);\n            throw new \\Exception($this->error);\n        }\n\n        $this->docker_installed = $server->validateDockerEngine();\n        $this->docker_compose_installed = $server->validateDockerCompose();\n        if (! $this->docker_installed || ! $this->docker_compose_installed) {\n            $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>.';\n            $server->update([\n                'validation_logs' => $this->error,","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/coollabsio/coolify/blob/70b9acc42467278373e00de77abb40684e25b395/app/Actions/Server/ValidateServer.php#L63-L99","documentation":"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.","triggerScenarios":"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.","commonSituations":"Niche/minimal/BSD hosts, containers used as 'servers', customized OS images with a nonstandard ID= line.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if ($server->validateOS() === false) {\n    return 'OS not supported. Install Docker manually, then re-validate.';\n}\nValidateServer::run($server);","typeGuard":"function isSupportedOs(\\App\\Models\\Server $server): bool\n{\n    return $server->validateOS() !== false;\n}","tryCatchPattern":"try {\n    ValidateServer::run($server);\n} catch (\\Exception $e) {\n    if (str_contains($e->getMessage(), 'OS type is not supported')) {\n        // permanent: manual Docker install or OS change required\n    } else {\n        throw $e;\n    }\n}","preventionTips":["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."],"tags":["os-detection","server-validation","docker","ssh"],"backgroundTag":"unsupported-operating-system","analyzedSha":"70b9acc42467278373e00de77abb40684e25b395","analyzedAt":"2026-08-17T01:41:01.313Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}