{"record":{"id":"95096b447af6dd5c","repo":"gohugoio/hugo","slug":"failed-to-create-file-caches-from-configuration","errorCode":null,"errorMessage":"failed to create file caches from configuration: %w","messagePattern":"failed to create file caches from configuration: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/allconfig/allconfig.go","lineNumber":1175,"sourceCode":"\t\t\tlangConfigMap[k] = clone\n\t\tcase hmaps.ParamsMergeStrategy:\n\n\t\tdefault:\n\t\t\tpanic(fmt.Sprintf(\"unknown type in languages config: %T\", v))\n\n\t\t}\n\t}\n\n\tbcfg.PublishDir = all.PublishDir\n\tres.BaseConfig = bcfg\n\tall.CommonDirs.CacheDir = bcfg.CacheDir\n\tfor _, l := range langConfigMap {\n\t\tl.CommonDirs.CacheDir = bcfg.CacheDir\n\t}\n\n\tcaches, err := filecache.NewCaches(all.Caches, fs)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create file caches from configuration: %w\", err)\n\t}\n\n\tcm := &Configs{\n\t\tBase:              all,\n\t\tLanguageConfigMap: langConfigMap,\n\t\tLoadingInfo:       res,\n\t\tFileCaches:        caches,\n\t\tIsMultihost:       isMultihost,\n\t}\n\n\treturn cm, nil\n}\n\nfunc decodeConfigFromParams(fs afero.Fs, logger loggers.Logger, bcfg config.BaseConfig, p config.Provider, target *Config, keys []string) error {\n\tvar decoderSetups []decodeWeight\n\n\tif len(keys) == 0 {\n\t\tfor _, v := range allDecoderSetups {","sourceCodeStart":1157,"sourceCodeEnd":1193,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/config/allconfig/allconfig.go#L1157-L1193","documentation":"Returned after all language configs are decoded, when constructing the file cache backends via filecache.NewCaches from the `caches` config section. Each cache entry defines a `dir` and `maxAge`; Hugo builds an afero filesystem rooted at each compiled directory. If the cache directory configuration is invalid (unresolvable path, non-writable target, bad cacheDir), the caches cannot be created and the whole config load fails.","triggerScenarios":"Setting `cacheDir` to a path that cannot be created or written; overriding a per-cache `dir` to an invalid/relative path that resolves outside allowed roots; a `caches` section where a `maxAge` or `dir` field has the wrong type; the configured cache directory lives on a read-only filesystem.","commonSituations":"CI/container runs where `cacheDir` points to a missing or non-writable volume; setting `HUGO_CACHEDIR` env var to a path the process can't create; misconfigured `[caches]` entry with a non-string `dir`; deploying into a sandboxed environment that blocks the default `$TMPDIR/hugo_cache`.","solutions":["Check the wrapped error for the offending cache key and path.","Verify the `cacheDir` (or `HUGO_CACHEDIR`) exists and is writable: `mkdir -p <dir> && touch <dir>/w`.","Reset `[caches]` overrides to defaults and confirm the build runs, then re-add overrides one at a time.","On CI, set an explicit writable `cacheDir` such as `/tmp/hugo_cache` or a runner-managed cache path."],"exampleFix":"# before\ncacheDir = \"/nonexistent/path\"\n\n# after\ncacheDir = \"/tmp/hugo_cache\"","handlingStrategy":"validation","validationCode":"# Ensure the cache dir is writable before building\nDIR=\"${HUGO_CACHEDIR:-${TMPDIR:-/tmp}/hugo_cache}\"\nmkdir -p \"$DIR\" && [ -w \"$DIR\" ] && echo \"cache ok\" || echo \"cache FAIL: $DIR\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set an explicit, writable `cacheDir` in CI rather than relying on defaults.","Avoid overriding per-cache `dir` unless necessary; document the chosen paths.","On read-only or sandboxed environments, point cacheDir at a tmpfs/runner cache path."],"tags":["config","cache","filesystem","permissions"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}