What causes "failed to decode filecache config: %w" in gohugoio/hugo?

Ensure maxAge uses valid Go duration syntax (e.g. "24h", "30m", "300ms") or -1 for forever or 0 for disabled

failed to decode filecache config: %w

Error message

failed to decode filecache config: %w

What it means

Each cache entry in the user config is decoded into a FileCacheConfig via mapstructure (filecache_config.go:229-242). If a field value has the wrong type — most commonly maxAge not being a valid duration string — the decode fails and the error is wrapped with this message.

Source

Thrown at cache/filecache/filecache_config.go:241

		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 == "" {
			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)

View on GitHub (pinned to 52c9bd7908)

Solutions

Ensure maxAge uses valid Go duration syntax (e.g. "24h", "30m", "300ms") or -1 for forever or 0 for disabled
Verify dir is a string value
Validate the config file's overall syntax with a linter

Example fix

# before
[caches.modules]
maxAge = "2 days"
# after
maxAge = "48h"

Defensive patterns

Strategy: validation

Validate before calling

// Validate duration strings before they reach the config decoder.
func validateMaxAge(s string) error {
    if s == "-1" || s == "0" {
        return nil
    }
    _, err := time.ParseDuration(s)
    return err
}

Prevention

Use Go duration syntax for maxAge (ns, us, ms, s, m, h)
Validate config files with hugo config before building
Avoid non-standard duration formats like '2 days'

When it happens

Trigger: Setting maxAge to an unparseable value like "abc" or "2 days", or providing dir as a non-string type.

Common situations: Invalid duration syntax in maxAge (missing unit, wrong unit); YAML/TOML/JSON type mismatches; copy-paste from docs that use unsupported duration formats.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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