{"id":"239e6fbf5e50d6df","repo":"gohugoio/hugo","slug":"failed-to-create-cache-dir-w","errorCode":null,"errorMessage":"failed to create cache dir: %w","messagePattern":"failed to create cache dir: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helpers/path.go","lineNumber":253,"sourceCode":"\t}\n\n\treturn f, err\n}\n\n// GetCacheDir returns a cache dir from the given filesystem and config.\n// The dir will be created if it does not exist.\nfunc GetCacheDir(fs afero.Fs, cacheDir string) (string, error) {\n\tcacheDir = cacheDirDefault(cacheDir)\n\n\tif cacheDir != \"\" {\n\t\texists, err := DirExists(cacheDir, fs)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\tif !exists {\n\t\t\terr := fs.MkdirAll(cacheDir, 0o777) // Before umask\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to create cache dir: %w\", err)\n\t\t\t}\n\t\t}\n\t\treturn cacheDir, nil\n\t}\n\n\tconst hugoCacheBase = \"hugo_cache\"\n\n\t// Avoid filling up the home dir with Hugo cache dirs from development.\n\tif !htesting.IsTest {\n\t\tuserCacheDir, err := os.UserCacheDir()\n\t\tif err == nil {\n\t\t\tcacheDir := filepath.Join(userCacheDir, hugoCacheBase)\n\t\t\tif err := fs.Mkdir(cacheDir, 0o777); err == nil || os.IsExist(err) {\n\t\t\t\treturn cacheDir, nil\n\t\t\t}\n\t\t}\n\t}\n","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/helpers/path.go#L235-L271","documentation":"helpers.GetCacheDir resolves Hugo's cache directory (from the `cacheDir` config, HUGO_CACHEDIR, or a default) and creates it with MkdirAll if it doesn't exist. This error wraps the underlying filesystem error when that MkdirAll fails, meaning Hugo cannot set up the directory used for module downloads, image processing cache, and getresource caches.","triggerScenarios":"MkdirAll on the resolved cache path returns an error: the configured `cacheDir` points into a location the user lacks write permission for, a path component exists as a regular file, the disk is full, or the path is on a read-only mount. Occurs at startup of any hugo build/server command that initializes caches.","commonSituations":"CI containers running as a non-root user with `cacheDir` or HUGO_CACHEDIR set to a root-owned path like /var/hugo_cache; read-only root filesystems in hardened containers (need a writable volume for the cache); Windows/网络 drives with restricted ACLs; a stale file occupying the configured cache path.","solutions":["Check the wrapped error detail (permission denied, read-only file system, not a directory) and point `cacheDir`/HUGO_CACHEDIR at a writable location, e.g. a path under the CI workspace or $HOME.","In containers, mount a writable volume and set `HUGO_CACHEDIR=/tmp/hugo_cache` (or similar) so cache creation succeeds.","If a file exists at the cache path, remove or rename it so a directory can be created.","Fix ownership/permissions on the parent directory (`chown`/`chmod`) if the path itself is correct."],"exampleFix":"# before (CI)\nhugo --minify   # HUGO_CACHEDIR=/var/hugo_cache, not writable by build user\n\n# after\nexport HUGO_CACHEDIR=$GITHUB_WORKSPACE/.hugo_cache\nhugo --minify","handlingStrategy":"try-catch","validationCode":"// Verify the cache dir is creatable/writable before invoking Hugo\nif err := os.MkdirAll(cacheDir, 0o755); err != nil { log.Fatalf(\"cacheDir unusable: %v\", err) }\nf, err := os.CreateTemp(cacheDir, \"probe*\"); if err == nil { f.Close(); os.Remove(f.Name()) }","typeGuard":null,"tryCatchPattern":"if err := run(); err != nil {\n    if errors.Is(err, fs.ErrPermission) || strings.Contains(err.Error(), \"failed to create cache dir\") {\n        // point cacheDir at a writable location and retry once\n    }\n}","preventionTips":["Set `cacheDir` explicitly in config (or HUGO_CACHEDIR) to a directory the build user owns","In containers/CI, mount or pre-create the cache dir with correct permissions","Don't point cacheDir at read-only or noexec-mounted filesystems"],"tags":["hugo","cache","filesystem","permissions","ci"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}