{"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/8a468df065a75c1c7cf9f6850f32148746590ea5/config/allconfig/allconfig.go#L1157-L1193","documentation":"Raised in fromLoadConfigResult (allconfig.go:1175) when filecache.NewCaches cannot build Hugo's file caches from the compiled `caches` config. After all language configs are decoded, Hugo instantiates the cache set (getjson, getcsv, images, assets, modules, etc.) with resolved directories and TTLs; failure means a cache entry is invalid or its directory cannot be created.","triggerScenarios":"An invalid `[caches.<name>]` config (unparseable maxAge, bad dir template token), a cacheDir/resourceDir path that cannot be created due to permissions or a read-only filesystem, or an unknown cache name in config.","commonSituations":"CI/containers with read-only or non-writable cache locations, HUGO_CACHEDIR pointing to an inaccessible path, typos in caches config, or disk-full/permission issues under /tmp or the user cache dir.","solutions":["Read the wrapped error to see which cache or path failed, and fix that `[caches.*]` entry (valid dir with :cacheDir/:project tokens, valid maxAge duration).","Ensure the cache directory (config cacheDir or HUGO_CACHEDIR) exists and is writable by the build user.","Set cacheDir explicitly to a writable location in restricted environments (e.g. HUGO_CACHEDIR=/tmp/hugo_cache).","Remove custom caches config to fall back to defaults and reintroduce entries one at a time."],"exampleFix":"# before\n[caches.getjson]\nmaxAge = \"forever\"\n# after\n[caches.getjson]\nmaxAge = -1  # -1 means never expire","handlingStrategy":"validation","validationCode":"// Validate [caches] entries before load: each cache needs a known name,\n// a valid dir template and a parseable maxAge duration\nfor name, c := range cfg.GetStringMap(\"caches\") {\n    m := c.(map[string]any)\n    if ma, ok := m[\"maxAge\"].(string); ok {\n        if _, err := time.ParseDuration(ma); err != nil && ma != \"-1\" {\n            return fmt.Errorf(\"caches.%s.maxAge invalid: %v\", name, err)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to create file caches\") {\n    return fmt.Errorf(\"inspect the [caches] section: check dir placeholders (:cacheDir/:resourceDir) and maxAge values: %w\", err)\n}","preventionTips":["Only use known cache names (getjson, getcsv, images, assets, modules, getresource)","Use valid duration strings for maxAge (e.g. \"24h\", \"-1\" for forever)","Use the :cacheDir / :resourceDir / :project placeholders in dir, not raw absolute paths on shared CI","Ensure cacheDir is writable in CI environments"],"tags":["hugo","config","filecache","filesystem"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}