{"record":{"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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/helpers/path.go#L235-L271","documentation":"helpers.GetCacheDir (helpers/path.go:251) MkdirAll's the configured cacheDir (0o777 before umask) when it does not yet exist. This wraps the MkdirAll failure. The cacheDir comes from the cacheDir base setting or the --cacheDir flag.","triggerScenarios":"The configured cacheDir points to a path that cannot be created: permission denied on a parent, read-only filesystem, disk/inode full, or an otherwise invalid path.","commonSituations":"CI on a read-only checkout; cacheDir on a volume the Hugo user cannot write to; full disk/tmpfs; cacheDir with a nonexistent user home.","solutions":["Point cacheDir at a writable location (set cacheDir in config or pass --cacheDir).","Fix permissions on the cacheDir path and its parents (chmod/chown).","Free disk space / inodes on the target volume.","Let Hugo fall back to the user cache dir by leaving cacheDir unset on a writable home."],"exampleFix":"# before: cacheDir on a read-only mount\n$ hugo --cacheDir /opt/hugo-cache   # /opt is read-only\n\n# after\n$ hugo --cacheDir /tmp/hugo-cache","handlingStrategy":"validation","validationCode":"// Confirm the cacheDir is creatable before Hugo starts.\nfunc ValidateCacheDir(fs afero.Fs, cacheDir string) error {\n    exists, err := helpers.DirExists(cacheDir, fs)\n    if err != nil { return err }\n    if exists { return nil }\n    return fs.MkdirAll(cacheDir, 0o777)\n}","typeGuard":null,"tryCatchPattern":"if _, err := helpers.GetCacheDir(fs, cacheDir); err != nil {\n    return err\n}","preventionTips":["Point cacheDir at a writable volume (or leave unset for the user cache dir).","Ensure the Hugo user owns/permissions the cache dir.","Free disk space/inodes before builds."],"tags":["caching","filesystem","permissions"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}