docker/compose · error

initializing remote resource cache: %w

Error message

initializing remote resource cache: %w

What it means

Once the OCI resource is pulled, the loader needs a local cache directory (via cacheDir()) to store the extracted compose files keyed by content digest. If cacheDir() fails — typically because it cannot create or locate the cache path under the user's state directory — the pull aborts with this wrapped error. The %w preserves the filesystem-level cause.

Source

Thrown at pkg/remote/oci.go:146

	}

	local, ok := g.known[path]
	if !ok {
		ref, err := reference.ParseDockerRef(path[len(OciPrefix):])
		if err != nil {
			return "", err
		}

		resolver := oci.NewResolver(g.dockerCli.ConfigFile(), g.httpTransport(ctx), g.insecureRegistries...)

		descriptor, content, err := oci.Get(ctx, resolver, ref)
		if err != nil {
			return "", fmt.Errorf("failed to pull OCI resource %q: %w", ref, err)
		}

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

		local = filepath.Join(cache, descriptor.Digest.Hex())
		if _, err = os.Stat(local); os.IsNotExist(err) {

			// a Compose application bundle is published as an image index
			if images.IsIndexType(descriptor.MediaType) {
				var index spec.Index
				err = json.Unmarshal(content, &index)
				if err != nil {
					return "", err
				}
				found := false
				for _, manifest := range index.Manifests {
					if manifest.ArtifactType != oci.ComposeProjectArtifactType {
						continue
					}
					found = true

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Inspect the wrapped error for the exact path, then fix permissions: `ls -la` the cache parent (usually ~/.docker/cli-plugins cache or compose state dir) and chown/chmod it for the current user.
2. If HOME is unset or read-only (containers, systemd units), set a writable HOME or the appropriate XDG state variable before running compose.
3. Free disk space if the volume is full; retry the pull afterwards.

// ensure a writable home/cache location before pulling OCI bundles
home, err := os.UserHomeDir()
if err != nil { return err }
info, err := os.Stat(filepath.Join(home, ".cache")) // or compose state dir
if err == nil && !info.IsDir() { return fmt.Errorf("cache parent is not a directory") }
// attempt creating it to surface permission issues early
if err := os.MkdirAll(cacheParent, 0o755); err != nil { return err }

When it happens

Trigger: cacheDir() failing on the machine: the parent directory of the cache cannot be created (read-only home, disk full), XDG/compose state dir points somewhere unwritable, or permission bits deny access. Happens only after a successful oci.Get, on the first pull of a given digest.

Common situations: Running compose as a user with no writable HOME; containerized/sandboxed environments with read-only filesystems; a stray root-owned directory inside the cache path left by a previous sudo run; full disk.

Related errors

• os.Stat(%q): %w
• notify.Add(%q): %w
• stat %q: %w
• inspecting %q: %w
• walking %q: %w

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