{"record":{"id":"e578aa44c8a0fbd3","repo":"docker/compose","slug":"initializing-remote-resource-cache-w","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/git.go","lineNumber":102,"sourceCode":"\tref, _, err := gitutil.ParseGitRef(path)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tlocal, ok := g.known[path]\n\tif !ok {\n\t\tif ref.Ref == \"\" {\n\t\t\tref.Ref = \"HEAD\" // default branch\n\t\t}\n\n\t\terr = g.resolveGitRef(ctx, path, ref)\n\t\tif err != nil {\n\t\t\treturn \"\", 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, ref.Ref)\n\t\tif _, err := os.Stat(local); os.IsNotExist(err) {\n\t\t\tif g.offline {\n\t\t\t\treturn \"\", nil\n\t\t\t}\n\t\t\terr = g.checkout(ctx, local, ref)\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", err\n\t\t\t}\n\t\t}\n\t\tg.known[path] = local\n\t}\n\tif ref.SubDir != \"\" {\n\t\tif err := validateGitSubDir(local, ref.SubDir); err != nil {\n\t\t\treturn \"\", err\n\t\t}","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/remote/git.go#L84-L120","documentation":"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.","triggerScenarios":"`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).","commonSituations":"Running Compose in minimal container images (distroless/scratch-derived) without HOME set; read-only filesystems; restrictive SELinux/AppArmor policies on the cache path.","solutions":["Ensure `$HOME` or `$XDG_CACHE_HOME` is set and writable in the environment running Compose","Fix permissions on the cache directory (~/.cache on Linux)","Pre-populate the cache or inline the remote file to avoid the remote loader"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# container/CI guard: a writable cache dir must exist\ndocker run -e HOME=/tmp/compose-home -v /tmp/compose-home:/tmp/compose-home ... docker:cli compose -f /src/compose.yaml config","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set HOME or XDG_CACHE_HOME explicitly in minimal containers running Compose","Ensure ~/.cache is writable (not read-only rootfs) before first use of git:// includes"],"tags":["compose","git-remote","cache","filesystem"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}