gohugoio/hugo · error

%q is not a valid cache name

Error message

%q is not a valid cache name

What it means

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.

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 8a468df065)

Solutions

1. 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).
2. Remove any invented cache sections; Hugo does not support user-defined cache names.
3. If the key is valid in a newer Hugo release, upgrade Hugo to the version that introduced it.

Example fix

# before (hugo.toml)
[caches.image]
maxAge = "24h"
# after
[caches.images]
maxAge = "24h"

validNames := map[string]bool{"getjson": true, "getcsv": true, "images": true, "assets": true, "modules": true, "getresource": true, "misc": true}
for name := range cachesConfig {
    if !validNames[strings.ToLower(name)] {
        return fmt.Errorf("unknown cache name %q", name)
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• must provide cache Dir
• %q is not a valid placeholder (valid values are :cacheDir or
• redirects must have either From or FromRe set
• failed to create config from result: %w
• failed to create config: %w

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/6e31b8b3abee9d9f.json. Report an issue: GitHub ↗.