coollabsio/coolify · error · RuntimeException

Failed to read the Docker Compose file from the repository.

Error message

Failed to read the Docker Compose file from the repository.

What it means

Catch-all for the Git compose-file read: the remote clone/cat failed with an error matching neither 'No such file' nor 'fatal: repository ... does not exist'. The original exception text was swallowed, so anything transient (SSH timeouts, DNS failures, disk full on the server, permission errors, unusual Git versions) lands here.

Source

Thrown at app/Models/Application.php:2174

        }
        try {
            $composeFileContent = instant_remote_process($commands, $this->destination->server);
        } catch (\Exception $e) {
            // Restore original values on failure only
            $this->docker_compose_location = $initialDockerComposeLocation;
            $this->base_directory = $initialBaseDirectory;
            $this->save();

            if (str($e->getMessage())->contains('No such file')) {
                throw new RuntimeException("Docker Compose file not found at: $workdir$composeFile (branch: {$this->git_branch})<br><br>Check if you used the right extension (.yaml or .yml) in the compose file name.");
            }
            if (str($e->getMessage())->contains('fatal: repository') && str($e->getMessage())->contains('does not exist')) {
                if ($this->deploymentType() === 'deploy_key') {
                    throw new RuntimeException('Your deploy key does not have access to the repository. Please check your deploy key and try again.');
                }
                throw new RuntimeException('Repository does not exist. Please check your repository URL and try again.');
            }
            throw new RuntimeException('Failed to read the Docker Compose file from the repository.');
        } finally {
            // Cleanup only - restoration happens in catch block
            $commands = collect([
                "rm -rf /tmp/{$uuid}",
            ]);
            instant_remote_process($commands, $this->destination->server, false);
        }
        if ($composeFileContent) {
            $this->docker_compose_raw = $composeFileContent;
            $this->save();
            $parsedServices = $this->parse();
            if ($this->docker_compose_domains) {
                $this->reconcileDockerComposeDomains($parsedServices);
            }

            return [
                'parsedServices' => $parsedServices,
                'initialDockerComposeLocation' => $this->docker_compose_location,

View on GitHub (pinned to 70b9acc424)

Solutions

Re-run the operation once — transient network/SSH failures are the most common cause.
Check disk space and SSH connectivity to the destination server (df -h, ssh root@server).
Manually execute the underlying clone+cat on the server to see the raw error Coolify hid.
If it persists, inspect Coolify logs for the original exception message just before this RuntimeException.

Defensive patterns

Strategy: retry

Validate before calling

// Cheap pre-flight: server reachable and disk available before clone
if (! $server->isReachable()) { /* defer deployment */ }
if (instant_remote_process(['df -h / | awk NR==2'], $server) reports < 1GB free) { /* alert before attempting git operations */ }

Try / catch

catch (RuntimeException $e) { if (str_contains($e->getMessage(), 'Failed to read the Docker Compose file')) { retry once after a short delay (transient SSH/network); on second failure capture the raw remote error by running the clone manually and surface it; } else { throw $e; } }

Prevention

Keep destination servers monitored for disk space and SSH reachability.
Log the underlying exception message before it is wrapped, so this catch-all is diagnosable.
Schedule retries with jitter for compose-from-git reads during git-host incidents.

When it happens

Trigger: Destination server temporarily unable to reach the git host (network blip, DNS failure); SSH to the server itself flaky; disk exhaustion breaking the clone; git not installed or too old on the destination server; credential prompts hanging until timeout.

Common situations: Self-hosted Git with intermittent uptime; server disk full from image/layer buildup; saturated SSH multiplexing during parallel deploys; custom git host requiring newer client features.

Related errors

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