coollabsio/coolify · error · RuntimeException

Docker Compose file not found at: $workdir$composeFile (bran

Error message

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.

What it means

While reading the compose file from a fresh shallow clone, Coolify cats '.{base_directory}{docker_compose_location}' on the server. The remote command fails with 'No such file' — the path/branch/extension combination does not exist in the cloned checkout — and Coolify translates it into this actionable RuntimeException (restoring the previously saved location fields first).

Source

Thrown at app/Models/Application.php:2166

                "cd /tmp/{$uuid}",
                $cloneCommand,
                'cd checkout',
                'git sparse-checkout init --cone',
                "git sparse-checkout set {$fileList->implode(' ')}",
                'git read-tree -mu HEAD',
                "cat .$workdir$composeFile",
            ]);
        }
        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();

View on GitHub (pinned to 70b9acc424)

Solutions

1. Set base directory and Docker Compose file location in the application's source settings to exactly match the repo layout (verify with git ls-tree on the configured branch).
2. Check the extension: use .yaml or .yml exactly as committed.
3. Confirm the file exists on the configured git branch and is actually committed (not gitignored).
4. Push the file or switch the tracked branch, then reload the compose in Coolify.

Example fix

# before: repo has compose at repo root
$application->base_directory = '/';
$application->docker_compose_location = '/docker-compose.yaml';

# after: match the real path
$application->base_directory = '/deploy';
$application->docker_compose_location = '/compose.yml';

// Verify the file exists on the tracked branch before saving the path
$files = instant_remote_process([
    "git ls-remote --heads {$repoUrl} {$branch} && echo OK",
], $server);
// or after a shallow clone:
$exists = instant_remote_process(["test -f ./{$baseDir}{$composeLocation} && echo yes || echo no"], $server);
if ($exists === 'no') { /* reject the location fields */ }

catch (RuntimeException $e) { if (str_contains($e->getMessage(), 'Docker Compose file not found')) { prompt for corrected base directory / compose location / branch; restore-and-retry once after fix; } else { throw $e; } }

When it happens

Trigger: docker_compose_location points at a file that is not on the configured git branch; base_directory wrong (file at repo root but '/subdir' configured); extension mismatch (.yaml configured, file is .yml); file name typo; file not committed or gitignored.

Common situations: Composing path like '/docker-compose.prod.yml' while the repo only has docker-compose.yml; branch switched from main to a branch lacking the file; case-sensitive filesystem vs 'Docker-Compose.yaml'; new file pushed to wrong branch.

Related errors

• Failed to read the Docker Compose file from the repository.
• Private key not found. Please add a private key to the appli
• $e->getMessage()
• Failed to read Git source. Please verify repository access a
• Your deploy key does not have access to the repository. Plea

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