coollabsio/coolify · error · RuntimeException

Instance URL (FQDN or APP_URL) must be set before claiming a

Error message

Instance URL (FQDN or APP_URL) must be set before claiming a server.

What it means

Error "Instance URL (FQDN or APP_URL) must be set before claiming a server." thrown in coollabsio/coolify.

Source

Thrown at app/Services/ServerTransfer/ServerTransferClaimer.php:36

     * best-effort — they cannot participate in the DB transaction.
     *
     * @return array{
     *     server_uuid: string,
     *     claim: array<string, mixed>,
     *     sentinel_rebound: bool,
     *     claim_written: bool,
     *     message: string
     * }
     */
    public function claim(Server $server, bool $writeRemote = true, bool $rebindSentinel = true): array
    {
        if ($server->id === 0) {
            throw new RuntimeException('Cannot claim the Coolify host itself.');
        }

        $instanceUrl = rtrim((string) (instanceSettings()->fqdn ?: config('app.url')), '/');
        if ($instanceUrl === '') {
            throw new RuntimeException('Instance URL (FQDN or APP_URL) must be set before claiming a server.');
        }

        $exportId = data_get($server->server_metadata, 'transfer.export_id');

        $claim = [
            'instance_url' => $instanceUrl,
            'server_uuid' => $server->uuid,
            'team_id' => $server->team_id,
            'claimed_at' => now()->toIso8601String(),
            'export_id' => $exportId,
            'schema_version' => ServerTransferBundle::SCHEMA_VERSION,
        ];

        $result = DB::transaction(function () use ($server, $claim, $rebindSentinel, $instanceUrl) {
            $server = Server::query()->with('settings')->lockForUpdate()->findOrFail($server->id);

            $sentinelRebound = false;
            if ($rebindSentinel && $server->settings) {

View on GitHub (pinned to 70b9acc424)

When it happens

Trigger: Thrown at app/Services/ServerTransfer/ServerTransferClaimer.php:36 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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