coollabsio/coolify · error · RuntimeException

Failed to read Git source. Please verify repository access a

Error message

Failed to read Git source. Please verify repository access and try again.

What it means

Before parsing a Docker Compose file straight from Git, Coolify performs getGitRemoteStatus(); when is_accessible comes back false the destination server could not authenticate to or read the repository at all, so it aborts with this message rather than attempting a clone. The concrete credential/network failure is in the underlying check, not in this message.

Source

Thrown at app/Models/Application.php:2114

    public function loadComposeFile($isInit = false, ?string $restoreBaseDirectory = null, ?string $restoreDockerComposeLocation = null)
    {
        // Use provided restore values or capture current values as fallback
        $initialDockerComposeLocation = $restoreDockerComposeLocation ?? $this->docker_compose_location;
        $initialBaseDirectory = $restoreBaseDirectory ?? $this->base_directory;
        if ($isInit && $this->docker_compose_raw) {
            return;
        }
        $uuid = new_public_id();
        ['commands' => $cloneCommand] = $this->generateGitImportCommands(deployment_uuid: $uuid, only_checkout: true, exec_in_docker: false, custom_base_dir: 'checkout');
        $cloneCommand = $this->gitCommandsAsShellCommand($cloneCommand);
        $cloneCommand = str_replace(' clone ', ' clone --quiet ', $cloneCommand);
        $workdir = rtrim($this->base_directory, '/');
        $composeFile = $this->docker_compose_location;
        $fileList = collect([".$workdir$composeFile"]);
        $gitRemoteStatus = $this->getGitRemoteStatus(deployment_uuid: $uuid);
        if (! $gitRemoteStatus['is_accessible']) {
            throw new RuntimeException('Failed to read Git source. Please verify repository access and try again.');
        }
        $getGitVersion = instant_remote_process(['git --version'], $this->destination->server, false);
        $gitVersion = str($getGitVersion)->explode(' ')->last();

        if (version_compare($gitVersion, '2.35.1', '<')) {
            $fileList = $fileList->map(function ($file) {
                $parts = explode('/', trim($file, '.'));
                $paths = collect();
                $currentPath = '';
                foreach ($parts as $part) {
                    $currentPath .= ($currentPath ? '/' : '').$part;
                    if (str($currentPath)->isNotEmpty()) {
                        $paths->push($currentPath);
                    }
                }

                return $paths;
            })->flatten()->unique()->values();

View on GitHub (pinned to 70b9acc424)

Solutions

Use the application's Git settings connection test to surface the concrete auth error for the repo.
From the destination server run git ls-remote <url> with the same credential to confirm access and see the raw Git error.
Rotate/re-attach the credential (new PAT, reinstall the GitHub App, re-add the deploy key's public half to the repo).
Check outbound DNS/connectivity from the destination server to the git host if credentials are fine.

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight before compose-from-git flows
$gitRemoteStatus = $application->getGitRemoteStatus(deployment_uuid: $uuid);
if (! $gitRemoteStatus['is_accessible']) { /* block with 'check URL/credentials/network' before cloning */ }

Try / catch

catch (RuntimeException $e) { if (str_contains($e->getMessage(), 'Failed to read Git source')) { surface credential/network hint and the last getGitRemoteStatus error detail; no auto-retry until credentials verified. } else { throw $e; } }

Prevention

Run the repo connection test from the application settings after any credential change.
Monitor PAT expiry dates and GitHub App installations; rotate before they lapse.
From the destination server, keep a working 'git ls-remote' baseline for each repo.

When it happens

Trigger: Repository URL typo'd or renamed; private repo with an expired/revoked PAT, wrong deploy key, or GitHub App installation removed; destination server lacks outbound DNS/network to the git host; self-hosted Git (Gitea/GitLab) down.

Common situations: GitHub PATs with expiry dates lapsing; deploy keys regenerated after rotation; firewall blocking port 22/443 from the server; organization removed the Coolify GitHub App; switching servers to one without network egress to the git host.

Related errors

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