{"record":{"id":"1e9a323df947594b","repo":"docker/compose","slug":"initializing-remote-resource-cache-w-1e9a32","errorCode":null,"errorMessage":"initializing remote resource cache: %w","messagePattern":"initializing remote resource cache: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/remote/oci.go","lineNumber":146,"sourceCode":"\t}\n\n\tlocal, ok := g.known[path]\n\tif !ok {\n\t\tref, err := reference.ParseDockerRef(path[len(OciPrefix):])\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\n\t\tresolver := oci.NewResolver(g.dockerCli.ConfigFile(), g.httpTransport(ctx), g.insecureRegistries...)\n\n\t\tdescriptor, content, err := oci.Get(ctx, resolver, ref)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to pull OCI resource %q: %w\", ref, err)\n\t\t}\n\n\t\tcache, err := cacheDir()\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"initializing remote resource cache: %w\", err)\n\t\t}\n\n\t\tlocal = filepath.Join(cache, descriptor.Digest.Hex())\n\t\tif _, err = os.Stat(local); os.IsNotExist(err) {\n\n\t\t\t// a Compose application bundle is published as an image index\n\t\t\tif images.IsIndexType(descriptor.MediaType) {\n\t\t\t\tvar index spec.Index\n\t\t\t\terr = json.Unmarshal(content, &index)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn \"\", err\n\t\t\t\t}\n\t\t\t\tfound := false\n\t\t\t\tfor _, manifest := range index.Manifests {\n\t\t\t\t\tif manifest.ArtifactType != oci.ComposeProjectArtifactType {\n\t\t\t\t\t\tcontinue\n\t\t\t\t\t}\n\t\t\t\t\tfound = true","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/remote/oci.go#L128-L164","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If HOME is unset or read-only (containers, systemd units), set a writable HOME or the appropriate XDG state variable before running compose.","Free disk space if the volume is full; retry the pull afterwards."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure a writable home/cache location before pulling OCI bundles\nhome, err := os.UserHomeDir()\nif err != nil { return err }\ninfo, err := os.Stat(filepath.Join(home, \".cache\")) // or compose state dir\nif err == nil && !info.IsDir() { return fmt.Errorf(\"cache parent is not a directory\") }\n// attempt creating it to surface permission issues early\nif err := os.MkdirAll(cacheParent, 0o755); err != nil { return err }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run compose as a regular user with a writable HOME.","In containers/CI, set HOME or XDG state vars to a writable path.","Never run compose via sudo such that root-owned dirs appear in the user's cache path."],"tags":["go","docker-compose","oci","filesystem","cache","permissions"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}