gohugoio/hugo · error

must provide cache Dir

Error message

must provide cache Dir

What it means

Returned by filecache.DecodeConfig when a [caches.<name>] override in site config decodes successfully but ends up with an empty Dir. The user's override replaced the default config for that cache (defaults are merged per-key via mapstructure into the existing entry), and an explicitly empty dir would leave Hugo nowhere to store cache files, so it fails fast rather than guessing a location.

Source

Thrown at cache/filecache/filecache_config.go:245

		}

		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 == "" {
			return c, errors.New("must provide cache Dir")
		}

		c[k] = cc

	}

	for k, v := range c {
		dir := filepath.ToSlash(filepath.Clean(v.Dir))
		hadSlash := strings.HasPrefix(dir, "/")
		parts := strings.Split(dir, "/")

		for i, part := range parts {
			if strings.HasPrefix(part, ":") {
				resolved, isResource, err := resolveDirPlaceholder(fs, bcfg, part)
				if err != nil {
					return c, err
				}
				if isResource {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Remove the empty `dir` line so the cache inherits its default (typically :cacheDir/:project-based).
2. To disable a cache, set `maxAge = 0` instead of blanking the directory.
3. If using env-var substitution, ensure the variable is set before running hugo.

Example fix

# before
[caches.images]
dir = ""
# after
[caches.images]
dir = ":cacheDir/images"

for name, c := range cachesConfig {
    if strings.TrimSpace(c.Dir) == "" {
        return fmt.Errorf("cache %q: dir must be set", name)
    }
}

When it happens

Trigger: Setting `dir = ""` explicitly under a caches entry, or a decode that clears the inherited default Dir; any [caches.X] map whose resulting merged config has Dir == "".

Common situations: Trying to 'disable' a cache by blanking its dir instead of setting maxAge = 0, YAML quirks that yield an empty string for dir, or templated/env-substituted config where the variable expands to empty (e.g. dir = "${HUGO_CACHEDIR}" unset).

Related errors

• %q is not a valid cache name
• %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/cf9be4215d1cacd7.json. Report an issue: GitHub ↗.