{"record":{"id":"42ae88f145daaeb2","repo":"coollabsio/coolify","slug":"unsupported-os-type-for-prerequisites-installation","errorCode":null,"errorMessage":"Unsupported OS type for prerequisites installation","messagePattern":"Unsupported OS type for prerequisites installation","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"app/Actions/Server/InstallPrerequisites.php","lineNumber":57,"sourceCode":"            ]);\n        } elseif ($supported_os_type->contains('sles')) {\n            $command = $command->merge([\n                \"echo 'Installing Prerequisites...'\",\n                'zypper update -y',\n                'command -v curl >/dev/null || zypper install -y curl',\n                'command -v wget >/dev/null || zypper install -y wget',\n                'command -v git >/dev/null || zypper install -y git',\n                'command -v jq >/dev/null || zypper install -y jq',\n            ]);\n        } elseif ($supported_os_type->contains('arch')) {\n            // Use -Syu for full system upgrade to avoid partial upgrade issues on Arch Linux\n            // --needed flag skips packages that are already installed and up-to-date\n            $command = $command->merge([\n                \"echo 'Installing Prerequisites for Arch Linux...'\",\n                'pacman -Syu --noconfirm --needed curl wget git jq',\n            ]);\n        } else {\n            throw new \\Exception('Unsupported OS type for prerequisites installation');\n        }\n\n        $command->push(\"echo 'Prerequisites installed successfully.'\");\n\n        return remote_process($command, $server);\n    }\n}\n","sourceCodeStart":39,"sourceCodeEnd":65,"githubUrl":"https://github.com/coollabsio/coolify/blob/70b9acc42467278373e00de77abb40684e25b395/app/Actions/Server/InstallPrerequisites.php#L39-L65","documentation":"Distinct from the validateOS() failures: this error is thrown when validateOS() SUCCEEDED but the distro matches no package-manager branch. validateOS() returns the whole matched SUPPORTED_OS group string, and the if/elseif chain tests contains('debian'), contains('rhel'), contains('sles'), contains('arch'). The one whitelisted OS with no branch is Alpine: 'alpine' is in SUPPORTED_OS so it passes detection, but there is no apk branch, so control reaches the else at line 57.","triggerScenarios":"Running automated prerequisite installation on an Alpine Linux server — validateOS() returns 'alpine', which contains neither 'debian', 'rhel', 'sles' nor 'arch', hitting the else throw.","commonSituations":"Alpine VMs/LXC containers chosen for small footprint; users confused because initial server validation accepted the host (Alpine is whitelisted for Docker detection) but prerequisite automation fails.","solutions":["Install prerequisites manually on Alpine: apk add --no-cache curl wget git jq, then re-run validation.","Use the validation endpoint without installation and provision the packages yourself (cloud-init, image build).","(Maintainer) add an Alpine branch before the else: merge([\"apk add --no-cache curl wget git jq\"])."],"exampleFix":"// app/Actions/Server/InstallPrerequisites.php — add before the final else\n} elseif ($supported_os_type->contains('alpine')) {\n    $command = $command->merge([\n        \"echo 'Installing Prerequisites for Alpine Linux...'\",\n        'apk add --no-cache curl wget git jq',\n    ]);\n} else {\n    throw new \\Exception('Unsupported OS type for prerequisites installation');\n}","handlingStrategy":"validation","validationCode":"$os = $server->validateOS();\n$automatedPrereqs = $os !== false && $os->contains('debian') || ($os && $os->contains('rhel')) || ($os && $os->contains('sles')) || ($os && $os->contains('arch'));\nif (! $automatedPrereqs) {\n    return 'Automated prerequisites unsupported for this OS. Install curl, wget, git, jq manually (Alpine: apk add --no-cache curl wget git jq).';\n}\nInstallPrerequisites::run($server);","typeGuard":"function supportsAutomatedPrerequisites(\\App\\Models\\Server $server): bool\n{\n    $os = $server->validateOS();\n    if ($os === false) {\n        return false;\n    }\n    return $os->contains('debian') || $os->contains('rhel') || $os->contains('sles') || $os->contains('arch');\n}","tryCatchPattern":"try {\n    InstallPrerequisites::run($server);\n} catch (\\Exception $e) {\n    if (str_contains($e->getMessage(), 'Unsupported OS type for prerequisites')) {\n        // Alpine or other whitelisted-but-unscripted OS: instruct manual install\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Remember SUPPORTED_OS (detection) is wider than the package-manager branches (install) — Alpine passes detection but has no apk branch.","Pre-install prerequisites on Alpine hosts yourself.","If you maintain a fork, add the apk branch and a test enumerating SUPPORTED_OS against the branches."],"tags":["alpine","package-manager","prerequisites","os-detection","server-setup"],"backgroundTag":"unsupported-operating-system","analyzedSha":"70b9acc42467278373e00de77abb40684e25b395","analyzedAt":"2026-08-17T01:41:01.313Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}