gohugoio/hugo · error

is not a valid cache name

Error message

%q is not a valid cache name

What it means

Hugo's file cache supports a fixed set of named caches: images, assets, modules, modulequeries, modulegitinfo, getresource, and misc (filecache_config.go:39-46). DecodeConfig iterates the user's caches config map and rejects any key not in this predefined set (filecache_config.go:225-226).

Solutions

1. Correct the cache name to match one of the valid keys (images, assets, modules, modulequeries, modulegitinfo, getresource, misc)
2. Remove the unknown cache entry from the config
3. Consult Hugo docs for the list of configurable cache names

Example fix

# before (hugo.toml)
[caches.image]
maxAge = "24h"
dir = ":cacheDir/images"
# after
caches:
  images:
    maxAge: '24h'
    dir: ':cacheDir/images'

// Validate cache names against the known set before deploying config.
var validCacheKeys = map[string]bool{
    "images": true, "assets": true, "modules": true,
    "modulequeries": true, "modulegitinfo": true,
    "getresource": true, "misc": true,
}
func validateCacheNames(m map[string]any) error {
    for k := range m {
        if !validCacheKeys[k] {
            return fmt.Errorf("%q is not a valid cache name", k)
        }
    }
    return nil
}

When it happens

Trigger: Adding a custom or misspelled entry under caches: in the config file, e.g. caches:image: or caches:mycache:.

Common situations: Typo in a cache name; attempting to define a custom named cache (unsupported); YAML key casing or indentation errors.

Related errors

• is not a valid placeholder (valid values are :cacheDir or…
• cache dir contains unresolved placeholders
• failed to decode filecache config
• is a root folder and not allowed as cache dir
• must resolve to an absolute directory

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/6e31b8b3abee9d9f. Report an issue: GitHub.

Appendix: source

Thrown at cache/filecache/filecache_config.go:226

func DecodeConfig(fs afero.Fs, bcfg config.BaseConfig, m map[string]any) (Configs, error) {
	c := make(Configs)
	valid := make(map[string]bool)
	// Add defaults
	for k, v := range defaultCacheConfigs {
		c[k] = v
		valid[k] = true
	}

	_, isOsFs := fs.(*afero.OsFs)

	for k, v := range m {
		if _, ok := v.(hmaps.Params); !ok {
			continue
		}
		var ok bool
		cc, ok := c[k]
		if !ok {
			return nil, fmt.Errorf("%q is not a valid cache name", k)
		}

		dc := &mapstructure.DecoderConfig{
			Result:           &cc,
			DecodeHook:       mapstructure.StringToTimeDurationHookFunc(),
			WeaklyTypedInput: true,
		}

		decoder, err := mapstructure.NewDecoder(dc)
		if err != nil {
			return c, err
		}

		if err := decoder.Decode(v); err != nil {
			return nil, fmt.Errorf("failed to decode filecache config: %w", err)
		}

		if cc.Dir == "" {

View on GitHub (pinned to 52c9bd7908)