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 prerequisites manually.

What it means

InstallPrerequisites (queued on the 'high' queue) first runs the same Server::validateOS() check: it SSHes out, reads /etc/os-release ID=, and requires a single match against the SUPPORTED_OS groups. When no group matches, it throws this generic \Exception before attempting any package-manager commands, telling the user to install prerequisites (curl/wget/git/jq) by hand.

Source

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

<?php

namespace App\Actions\Server;

use App\Models\Server;
use Lorisleiva\Actions\Concerns\AsAction;

class InstallPrerequisites
{
    use AsAction;

    public string $jobQueue = 'high';

    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 prerequisites manually.');
        }

        $command = collect([]);

        if ($supported_os_type->contains('debian')) {
            $command = $command->merge([
                "echo 'Installing Prerequisites...'",
                'apt-get update -y',
                'command -v curl >/dev/null || apt install -y curl',
                'command -v wget >/dev/null || apt install -y wget',
                'command -v git >/dev/null || apt install -y git',
                'command -v jq >/dev/null || apt install -y jq',
            ]);
        } elseif ($supported_os_type->contains('rhel')) {
            $command = $command->merge([
                "echo 'Installing Prerequisites...'",
                'command -v curl >/dev/null || dnf install -y curl',
                'command -v wget >/dev/null || dnf install -y wget',

View on GitHub (pinned to 70b9acc424)

Solutions

Install curl, wget, git and jq manually on the host with the distro's package manager, then re-validate.
Move to a supported OS if you want automated installs.
Verify /etc/os-release contents over SSH if you believe the distro is supported.

Defensive patterns

Strategy: validation

Validate before calling

if ($server->validateOS() === false) {
    return 'OS not supported for automated prerequisite installation. Install curl, wget, git and jq manually.';
}
InstallPrerequisites::run($server);

Type guard

function isAutoInstallableOs(\App\Models\Server $server): bool
{
    return $server->validateOS() !== false;
}

Try / catch

try {
    InstallPrerequisites::run($server);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'not supported for automated installation')) {
        // permanent: fall back to manual instructions
    } else {
        throw $e;
    }
}

Prevention

Bake curl/wget/git/jq into server images (cloud-init or packer) so this path never runs.
Validate the server first; the same OS check runs with friendlier reporting.
Stick to supported distros for hosts managed end-to-end by Coolify.

When it happens

Trigger: Dispatching InstallPrerequisites on a host whose distro ID (from /etc/os-release) is not in SUPPORTED_OS — nixos, gentoo, freebsd, or an image with missing/garbled os-release.

Common situations: Same class as the Docker-install error: unusual distros or minimal images; servers provisioned by tools that strip /etc/os-release.

Related errors

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