What causes "Unsupported OS type for prerequisites installation" in coollabsio/coolify?

Install prerequisites manually on Alpine: apk add --no-cache curl wget git jq, then re-run validation.

coollabsio/coolify · error · Exception

Unsupported OS type for prerequisites installation

Error message

Unsupported OS type for prerequisites installation

What it means

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.

Source

Thrown at app/Actions/Server/InstallPrerequisites.php:57

            ]);
        } elseif ($supported_os_type->contains('sles')) {
            $command = $command->merge([
                "echo 'Installing Prerequisites...'",
                'zypper update -y',
                'command -v curl >/dev/null || zypper install -y curl',
                'command -v wget >/dev/null || zypper install -y wget',
                'command -v git >/dev/null || zypper install -y git',
                'command -v jq >/dev/null || zypper install -y jq',
            ]);
        } elseif ($supported_os_type->contains('arch')) {
            // Use -Syu for full system upgrade to avoid partial upgrade issues on Arch Linux
            // --needed flag skips packages that are already installed and up-to-date
            $command = $command->merge([
                "echo 'Installing Prerequisites for Arch Linux...'",
                'pacman -Syu --noconfirm --needed curl wget git jq',
            ]);
        } else {
            throw new \Exception('Unsupported OS type for prerequisites installation');
        }

        $command->push("echo 'Prerequisites installed successfully.'");

        return remote_process($command, $server);
    }
}

View on GitHub (pinned to 70b9acc424)

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"]).

Example fix

// app/Actions/Server/InstallPrerequisites.php — add before the final else
} elseif ($supported_os_type->contains('alpine')) {
    $command = $command->merge([
        "echo 'Installing Prerequisites for Alpine Linux...'",
        'apk add --no-cache curl wget git jq',
    ]);
} else {
    throw new \Exception('Unsupported OS type for prerequisites installation');
}

Defensive patterns

Strategy: validation

Validate before calling

$os = $server->validateOS();
$automatedPrereqs = $os !== false && $os->contains('debian') || ($os && $os->contains('rhel')) || ($os && $os->contains('sles')) || ($os && $os->contains('arch'));
if (! $automatedPrereqs) {
    return 'Automated prerequisites unsupported for this OS. Install curl, wget, git, jq manually (Alpine: apk add --no-cache curl wget git jq).';
}
InstallPrerequisites::run($server);

Type guard

function supportsAutomatedPrerequisites(\App\Models\Server $server): bool
{
    $os = $server->validateOS();
    if ($os === false) {
        return false;
    }
    return $os->contains('debian') || $os->contains('rhel') || $os->contains('sles') || $os->contains('arch');
}

Try / catch

try {
    InstallPrerequisites::run($server);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'Unsupported OS type for prerequisites')) {
        // Alpine or other whitelisted-but-unscripted OS: instruct manual install
    } else {
        throw $e;
    }
}

Prevention

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.

When it happens

Trigger: Running automated prerequisite installation on an Alpine Linux server — validateOS() returns 'alpine', which contains neither 'debian', 'rhel', 'sles' nor 'arch', hitting the else throw.

Common situations: 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.

Related errors

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