gohugoio/hugo · error

failed to create file caches from configuration

Error message

failed to create file caches from configuration: %w

What it means

Returned after all language configs are decoded, when constructing the file cache backends via filecache.NewCaches from the `caches` config section. Each cache entry defines a `dir` and `maxAge`; Hugo builds an afero filesystem rooted at each compiled directory. If the cache directory configuration is invalid (unresolvable path, non-writable target, bad cacheDir), the caches cannot be created and the whole config load fails.

Solutions

1. Check the wrapped error for the offending cache key and path.
2. Verify the `cacheDir` (or `HUGO_CACHEDIR`) exists and is writable: `mkdir -p <dir> && touch <dir>/w`.
3. Reset `[caches]` overrides to defaults and confirm the build runs, then re-add overrides one at a time.
4. On CI, set an explicit writable `cacheDir` such as `/tmp/hugo_cache` or a runner-managed cache path.

Example fix

# before
cacheDir = "/nonexistent/path"

# after
cacheDir = "/tmp/hugo_cache"

# Ensure the cache dir is writable before building
DIR="${HUGO_CACHEDIR:-${TMPDIR:-/tmp}/hugo_cache}"
mkdir -p "$DIR" && [ -w "$DIR" ] && echo "cache ok" || echo "cache FAIL: $DIR"

When it happens

Trigger: Setting `cacheDir` to a path that cannot be created or written; overriding a per-cache `dir` to an invalid/relative path that resolves outside allowed roots; a `caches` section where a `maxAge` or `dir` field has the wrong type; the configured cache directory lives on a read-only filesystem.

Common situations: CI/container runs where `cacheDir` points to a missing or non-writable volume; setting `HUGO_CACHEDIR` env var to a path the process can't create; misconfigured `[caches]` entry with a non-string `dir`; deploying into a sandboxed environment that blocks the default `$TMPDIR/hugo_cache`.

Related errors

• failed to create workingDir
• failed to prune cache
• failled to create base cache directory
• invalid cache config
• invalid cache dir

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

Appendix: source

Thrown at config/allconfig/allconfig.go:1175

			langConfigMap[k] = clone
		case hmaps.ParamsMergeStrategy:

		default:
			panic(fmt.Sprintf("unknown type in languages config: %T", v))

		}
	}

	bcfg.PublishDir = all.PublishDir
	res.BaseConfig = bcfg
	all.CommonDirs.CacheDir = bcfg.CacheDir
	for _, l := range langConfigMap {
		l.CommonDirs.CacheDir = bcfg.CacheDir
	}

	caches, err := filecache.NewCaches(all.Caches, fs)
	if err != nil {
		return nil, fmt.Errorf("failed to create file caches from configuration: %w", err)
	}

	cm := &Configs{
		Base:              all,
		LanguageConfigMap: langConfigMap,
		LoadingInfo:       res,
		FileCaches:        caches,
		IsMultihost:       isMultihost,
	}

	return cm, nil
}

func decodeConfigFromParams(fs afero.Fs, logger loggers.Logger, bcfg config.BaseConfig, p config.Provider, target *Config, keys []string) error {
	var decoderSetups []decodeWeight

	if len(keys) == 0 {
		for _, v := range allDecoderSetups {

View on GitHub (pinned to 52c9bd7908)