{"id":"6e31b8b3abee9d9f","repo":"gohugoio/hugo","slug":"q-is-not-a-valid-cache-name","errorCode":null,"errorMessage":"%q is not a valid cache name","messagePattern":"%q is not a valid cache name","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cache/filecache/filecache_config.go","lineNumber":226,"sourceCode":"func DecodeConfig(fs afero.Fs, bcfg config.BaseConfig, m map[string]any) (Configs, error) {\n\tc := make(Configs)\n\tvalid := make(map[string]bool)\n\t// Add defaults\n\tfor k, v := range defaultCacheConfigs {\n\t\tc[k] = v\n\t\tvalid[k] = true\n\t}\n\n\t_, isOsFs := fs.(*afero.OsFs)\n\n\tfor k, v := range m {\n\t\tif _, ok := v.(hmaps.Params); !ok {\n\t\t\tcontinue\n\t\t}\n\t\tvar ok bool\n\t\tcc, ok := c[k]\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%q is not a valid cache name\", k)\n\t\t}\n\n\t\tdc := &mapstructure.DecoderConfig{\n\t\t\tResult:           &cc,\n\t\t\tDecodeHook:       mapstructure.StringToTimeDurationHookFunc(),\n\t\t\tWeaklyTypedInput: true,\n\t\t}\n\n\t\tdecoder, err := mapstructure.NewDecoder(dc)\n\t\tif err != nil {\n\t\t\treturn c, err\n\t\t}\n\n\t\tif err := decoder.Decode(v); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to decode filecache config: %w\", err)\n\t\t}\n\n\t\tif cc.Dir == \"\" {","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/cache/filecache/filecache_config.go#L208-L244","documentation":"Returned by filecache.DecodeConfig when the site config's caches map contains a key that is not one of Hugo's predefined cache names (images, assets, modules, getresource, misc, etc.). Hugo seeds the valid set from defaultCacheConfigs and rejects anything else, since each cache name maps to a specific internal subsystem — arbitrary user-defined caches are not supported.","triggerScenarios":"A [caches.<name>] section in hugo.toml/yaml/json where <name> is not a key in defaultCacheConfigs; e.g. [caches.image] (singular), [caches.getResource] misspelled, or an invented cache like [caches.mycache]. Only map-valued entries are checked, so it fires when the value is a Params table.","commonSituations":"Typos in the caches config (image vs images, module vs modules), copying config from a newer/older Hugo version that added or renamed a cache key (e.g. getresource, modulequeries), or guessing that custom cache buckets can be declared.","solutions":["Fix the key to one of the supported names — run `hugo config | grep -A2 caches` or check defaultCacheConfigs in cache/filecache/filecache_config.go for the exact set (e.g. images, assets, modules, getresource, misc).","Remove any invented cache sections; Hugo does not support user-defined cache names.","If the key is valid in a newer Hugo release, upgrade Hugo to the version that introduced it."],"exampleFix":"# before (hugo.toml)\n[caches.image]\nmaxAge = \"24h\"\n# after\n[caches.images]\nmaxAge = \"24h\"","handlingStrategy":"validation","validationCode":"validNames := map[string]bool{\"getjson\": true, \"getcsv\": true, \"images\": true, \"assets\": true, \"modules\": true, \"getresource\": true, \"misc\": true}\nfor name := range cachesConfig {\n    if !validNames[strings.ToLower(name)] {\n        return fmt.Errorf(\"unknown cache name %q\", name)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only configure cache keys documented for your Hugo version (getjson, getcsv, images, assets, modules, misc, getresource)","Check for typos in [caches] section keys — names are matched exactly","Re-check the docs after upgrading Hugo; valid cache names change between versions"],"tags":["hugo","filecache","config","validation"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}