coollabsio/coolify · error · Exception

Prerequisites ({$missingCommands}) could not be installed af

Error message

Prerequisites ({$missingCommands}) could not be installed after {$this->maxPrerequisiteInstallAttempts} attempts. Please install them manually.

What it means

During server onboarding, Coolify validates required commands on the target server via Server::validatePrerequisites() (ValidatePrerequisites action) and, when some are missing, starts an automatic install and waits via the activity monitor. Once prerequisiteInstallAttempts reaches maxPrerequisiteInstallAttempts (3) and validation still reports missing commands, onboarding aborts with the list of commands that could not be installed.

Source

Thrown at app/Livewire/Boarding/Index.php:367

            ]);
            $this->serverReachable = true;
        } catch (\Throwable $e) {
            $this->serverReachable = false;
            $this->createdServer->settings()->update([
                'is_reachable' => false,
            ]);

            return handleError(error: $e, livewire: $this);
        }

        try {
            // Check prerequisites
            $validationResult = $this->createdServer->validatePrerequisites();
            if (! $validationResult['success']) {
                // Check if we've exceeded max attempts
                if ($this->prerequisiteInstallAttempts >= $this->maxPrerequisiteInstallAttempts) {
                    $missingCommands = implode(', ', $validationResult['missing']);
                    throw new \Exception("Prerequisites ({$missingCommands}) could not be installed after {$this->maxPrerequisiteInstallAttempts} attempts. Please install them manually.");
                }

                // Start async installation and wait for completion via ActivityMonitor
                $activity = $this->createdServer->installPrerequisites();
                $this->prerequisiteInstallAttempts++;
                $this->dispatch('activityMonitor', $activity->id, 'prerequisitesInstalled');

                // Return early - handlePrerequisitesInstalled() will be called when installation completes
                return;
            }

            // Prerequisites are already installed, continue with validation
            $this->continueValidation();
        } catch (\Throwable $e) {
            return handleError(error: $e, livewire: $this);
        }
    }

View on GitHub (pinned to 70b9acc424)

Solutions

SSH in and install the listed commands manually (e.g. `apt-get update && apt-get install -y curl wget git jq`), then retry validation in the boarding UI
Verify the server has working outbound internet and a functioning package manager (run `apt-get update` or `dnf update` by hand)
Use a supported OS (Ubuntu/Debian/Rocky/Alma) and an SSH user with root or passwordless sudo

Defensive patterns

Strategy: retry

Validate before calling

# from your workstation, before onboarding the server:
ssh user@server 'for c in curl wget git jq; do command -v $c >/dev/null || echo missing: $c; done'

Prevention

Pre-install Coolify's required commands in your server bootstrap (ansible, cloud-init, Dockerfile)
Confirm the SSH user has root or passwordless sudo before starting onboarding
Allow outbound access to the distro's package mirrors

When it happens

Trigger: installPrerequisites() runs but the server cannot complete it: no outbound access to package mirrors, an unsupported or broken package manager, a non-root SSH user without sudo, or a read-only filesystem - so after 3 attempts the commands are still missing.

Common situations: Hardened or firewalled servers with blocked egress; minimal or exotic distros (Alpine, NixOS); CI containers without a package manager; cloud images with broken apt/yum sources.

Related errors

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