docker/compose · error

failed to access repository at %s: %s

Error message

failed to access repository at %s:
 %s

What it means

`git ls-remote` failed with an exit code other than 2 — the command itself could not complete against the remote. The message embeds the remote URL and the raw git output (stderr included, since CombinedOutput is used), which typically names the real cause: auth failure, DNS/network error, or repository not found.

Source

Thrown at pkg/remote/git.go:181

	}

	if relPath == ".." || strings.HasPrefix(relPath, "../") || strings.HasPrefix(relPath, "..\\") {
		return fmt.Errorf("git subdirectory escapes base directory: %s", subDir)
	}

	return nil
}

func (g gitRemoteLoader) resolveGitRef(ctx context.Context, path string, ref *gitutil.GitRef) error {
	if !commitSHA.MatchString(ref.Ref) {
		cmd := exec.CommandContext(ctx, "git", "ls-remote", "--exit-code", ref.Remote, ref.Ref)
		cmd.Env = g.gitCommandEnv()
		out, err := cmd.CombinedOutput()
		if err != nil {
			if cmd.ProcessState.ExitCode() == 2 {
				return fmt.Errorf("repository does not contain ref %s, output: %q: %w", path, string(out), err)
			}
			return fmt.Errorf("failed to access repository at %s:\n %s", ref.Remote, out)
		}
		if len(out) < 40 {
			return fmt.Errorf("unexpected git command output: %q", string(out))
		}
		sha := string(out[:40])
		if !commitSHA.MatchString(sha) {
			return fmt.Errorf("invalid commit sha %q", sha)
		}
		ref.Ref = sha
	}
	return nil
}

func (g gitRemoteLoader) checkout(ctx context.Context, path string, ref *gitutil.GitRef) error {
	err := os.MkdirAll(path, 0o700)
	if err != nil {
		return err
	}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Read the embedded git output — it states the underlying failure (auth, TLS, DNS)
2. Verify access manually: `git ls-remote <remote>` from the same machine/user
3. For private repos over HTTPS, configure a credential helper or use an SSH remote with a loaded key
4. Fix network/proxy issues (HTTPS_PROXY, CA certs) if TLS or DNS is the cause

# preflight connectivity and auth to the git remote
git ls-remote https://github.com/org/repo.git HEAD >/dev/null \
  || { echo "cannot reach/authenticate git remote" >&2; exit 1; }

# transient network/TLS failures when loading git includes may be retried with backoff
for i in 1 2 3; do
  if docker compose config >/dev/null 2>err.txt; then break; fi
  grep -qE 'failed to access repository' err.txt || { cat err.txt >&2; exit 1; }
  sleep $((i * 2))
done

When it happens

Trigger: No network connectivity, `SSL certificate problem`, `Repository not found`, `could not read Username` (missing credentials for private repos), or a malformed remote URL — all returned when resolving a git include ref.

Common situations: CI runners without git credentials for private includes; corporate proxies intercepting TLS; typos in the remote URL; running with `--offline` incorrectly set; SSH remotes without keys.

Related errors

• failed to resolve digest for %s: %w
• COMPOSE_EXPERIMENTAL_GIT_REMOTE environment variable expects
• git remote resource is disabled by %q
• initializing remote resource cache: %w
• git subdirectory must be relative, got: %s

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/0b51706aa63d7255. Report an issue: GitHub.