docker/compose · error

initializing remote resource cache: %w

Error message

initializing remote resource cache: %w

What it means

After resolving a git ref for a remote include, the loader prepares a local cache directory under the user cache dir (via `cacheDir()`); if that setup fails (unresolvable home dir, unwritable filesystem, permission denied), this wrapped error is returned.

Source

Thrown at pkg/remote/git.go:102

	ref, _, err := gitutil.ParseGitRef(path)
	if err != nil {
		return "", err
	}

	local, ok := g.known[path]
	if !ok {
		if ref.Ref == "" {
			ref.Ref = "HEAD" // default branch
		}

		err = g.resolveGitRef(ctx, path, ref)
		if err != nil {
			return "", err
		}

		cache, err := cacheDir()
		if err != nil {
			return "", fmt.Errorf("initializing remote resource cache: %w", err)
		}

		local = filepath.Join(cache, ref.Ref)
		if _, err := os.Stat(local); os.IsNotExist(err) {
			if g.offline {
				return "", nil
			}
			err = g.checkout(ctx, local, ref)
			if err != nil {
				return "", err
			}
		}
		g.known[path] = local
	}
	if ref.SubDir != "" {
		if err := validateGitSubDir(local, ref.SubDir); err != nil {
			return "", err
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Ensure `$HOME` or `$XDG_CACHE_HOME` is set and writable in the environment running Compose
2. Fix permissions on the cache directory (~/.cache on Linux)
3. Pre-populate the cache or inline the remote file to avoid the remote loader

# container/CI guard: a writable cache dir must exist
docker run -e HOME=/tmp/compose-home -v /tmp/compose-home:/tmp/compose-home ... docker:cli compose -f /src/compose.yaml config

When it happens

Trigger: `os.UserCacheDir()`/MkdirAll failing: `HOME`/`XDG_CACHE_HOME` unset in a container, read-only root filesystem, or permission problems on `~/.cache` — hit the first time a `git://` include is loaded (cache miss).

Common situations: Running Compose in minimal container images (distroless/scratch-derived) without HOME set; read-only filesystems; restrictive SELinux/AppArmor policies on the cache path.

Related errors

• cannot take exclusive lock for project %q: %w
• failed to access env file %s: %w
• resolving symlink for %q: %w
• COMPOSE_EXPERIMENTAL_GIT_REMOTE environment variable expects
• git remote resource is disabled by %q

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