gohugoio/hugo · critical

invalid cache dir: %q

Error message

invalid cache dir: %q

What it means

A panic in FileCacheConfig.init() (cache/filecache/filecache_config.go:133) when the compiled cache directory is shorter than 5 characters. This sanity check prevents cache eviction from operating on a root or near-root path, which could delete unrelated files.

Source

Thrown at cache/filecache/filecache_config.go:133

	MaxAge time.Duration

	// The directory where files are stored.
	Dir string

	fileCacheConfigInternal `json:"-"`
}

func (cfg *FileCacheConfig) init() error {
	if cfg.DirCompiled == "" {
		// From unit tests. Just check that it does not contain any placeholders.
		if strings.Contains(cfg.Dir, ":") {
			return fmt.Errorf("cache dir %q contains unresolved placeholders", cfg.Dir)
		}
		cfg.DirCompiled = cfg.Dir
	}
	// Sanity check the config.
	if len(cfg.DirCompiled) < 5 {
		panic(fmt.Sprintf("invalid cache dir: %q", cfg.DirCompiled))
	}
	return nil
}

type fileCacheConfigInternal struct {
	DirCompiled string

	name          string // The name of this cache, e.g. "images", "modules" etc.
	entryIsDir    bool   // when set, the cache entries represents directories directly below the base dir.
	isReadOnly    bool   // when set, the cache is read only and needs to be pruned differently. This is used for the Go modules cache.
	IsResourceDir bool   //  resources/_gen will get its own composite filesystem that also checks any theme. TODO(bep) unexport this.
}

// MarshalJSON marshals FileCacheConfig to JSON with MaxAge as a human-readable string.
func (c FileCacheConfig) MarshalJSON() ([]byte, error) {
	var maxAge any
	if c.MaxAge == -1 {
		maxAge = -1

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Provide a full, meaningful absolute path for the cache directory
2. Prefer Hugo defaults (:cacheDir/:project) over a hand-rolled short dir
3. Verify the --cacheDir flag / cacheDir config resolves to a real directory of normal length

if len(cfg.DirCompiled) < 5 {
    return fmt.Errorf("cache dir %q is too short; use a full absolute path", cfg.DirCompiled)
}

When it happens

Trigger: A FileCacheConfig whose DirCompiled resolves to an extremely short string such as '/a' or a single letter, typically from a malformed custom Dir or a broken placeholder resolution.

Common situations: Hand-rolled cacheDir config pointing at a near-root relative path; corrupted resolution of :cacheDir to an empty/truncated value.

Related errors

• invalid cache config: %s
• failed to create file caches from configuration: %w
• publishDir is empty
• workingDir is too short
• Unable to locate config file or config directory. Perhaps yo

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