{"record":{"id":"21824f43a0ec4122","repo":"gohugoio/hugo","slug":"q-must-resolve-to-an-absolute-directory","errorCode":null,"errorMessage":"%q must resolve to an absolute directory","messagePattern":"%q must resolve to an absolute directory","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cache/filecache/filecache_config.go","lineNumber":278,"sourceCode":"\t\t\t\tif err != nil {\n\t\t\t\t\treturn c, err\n\t\t\t\t}\n\t\t\t\tif isResource {\n\t\t\t\t\tv.IsResourceDir = true\n\t\t\t\t}\n\t\t\t\tparts[i] = resolved\n\t\t\t}\n\t\t}\n\n\t\tdir = path.Join(parts...)\n\t\tif hadSlash {\n\t\t\tdir = \"/\" + dir\n\t\t}\n\t\tv.DirCompiled = filepath.Clean(filepath.FromSlash(dir))\n\n\t\tif !v.IsResourceDir {\n\t\t\tif isOsFs && !filepath.IsAbs(v.DirCompiled) {\n\t\t\t\treturn c, fmt.Errorf(\"%q must resolve to an absolute directory\", v.DirCompiled)\n\t\t\t}\n\n\t\t\t// Avoid cache in root, e.g. / (Unix) or c:\\ (Windows)\n\t\t\tif len(strings.TrimPrefix(v.DirCompiled, filepath.VolumeName(v.DirCompiled))) == 1 {\n\t\t\t\treturn c, fmt.Errorf(\"%q is a root folder and not allowed as cache dir\", v.DirCompiled)\n\t\t\t}\n\t\t}\n\n\t\tif !strings.HasPrefix(v.DirCompiled, \"_gen\") {\n\t\t\t// We do cache eviction (file removes) and since the user can set\n\t\t\t// his/hers own cache directory, we really want to make sure\n\t\t\t// we do not delete any files that do not belong to this cache.\n\t\t\t// We do add the cache name as the root, but this is an extra safe\n\t\t\t// guard. We skip the files inside /resources/_gen/ because\n\t\t\t// that would be breaking.\n\t\t\tv.DirCompiled = filepath.Join(v.DirCompiled, FilecacheRootDirname, k)\n\t\t} else {\n\t\t\tv.DirCompiled = filepath.Join(v.DirCompiled, k)","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/cache/filecache/filecache_config.go#L260-L296","documentation":"After resolving placeholders, DecodeConfig checks that non-resource cache dirs on the real OS filesystem resolve to an absolute path (filecache_config.go:276-278). Hugo requires absolute paths because it performs file eviction/removal and a relative base could be unsafe or ambiguous depending on the working directory.","triggerScenarios":"Setting a cache's dir (or cacheDir) to a relative path like \"./cache\" or \"my-cache\" while running on the OS filesystem.","commonSituations":"Relative paths in config files; running Hugo from varying working directories; portable config that works on one machine but not another.","solutions":["Use an absolute path for the cache dir (e.g. /home/user/.cache/hugo)","Use the :cacheDir placeholder which Hugo resolves to an absolute location","Pass --cacheDir /absolute/path on the command line"],"exampleFix":"# before\ncacheDir = \"./mycache\"\n# after\ncacheDir = \"/home/user/.cache/hugo\"","handlingStrategy":"validation","validationCode":"// Ensure cacheDir is absolute before running Hugo.\nfunc ensureAbsCacheDir(dir string) string {\n    if !filepath.IsAbs(dir) {\n        abs, _ := filepath.Abs(dir)\n        return abs\n    }\n    return dir\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use absolute paths for cacheDir in config","Use the :cacheDir placeholder which Hugo resolves absolutely","Avoid relative paths in shared/committed config files"],"tags":["cache","filecache","config","paths","absolute-path","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}