gohugoio/hugo · error

is not a valid placeholder (valid values are :cacheDir or…

Error message

%q is not a valid placeholder (valid values are :cacheDir or :resourceDir)

What it means

Cache dir paths may contain only three placeholders: :cacheDir, :resourceDir, and :project (filecache_config.go:306-316). resolveDirPlaceholder rejects any other colon-prefixed token. Note matching is case-insensitive (:resourceDir and :resourcedir both work).

Solutions

1. Use only :cacheDir, :resourceDir, or :project
2. Replace the invalid placeholder with a literal absolute path
3. Check for typos in the placeholder spelling (case-insensitive but spelling must match)

Example fix

# before
dir = ":themes/cache"
# after
dir = ":cacheDir/themes"

// Validate placeholders in cache dir strings.
var validPlaceholders = []string{":cachedir", ":resourcedir", ":project"}
func validatePlaceholders(dir string) error {
    for _, part := range strings.Split(dir, "/") {
        if strings.HasPrefix(part, ":") {
            if !slices.Contains(validPlaceholders, strings.ToLower(part)) {
                return fmt.Errorf("%q is not a valid placeholder", part)
            }
        }
    }
    return nil
}

When it happens

Trigger: Using an unsupported placeholder like :themes, :temp, :workingDir, or a typo like :cacheDirr in a cache dir string.

Common situations: Guessing placeholder names from other Hugo concepts; typos; copy-paste errors from outdated docs.

Related errors

• cache dir contains unresolved placeholders
• is not a valid cache name
• failed to decode filecache config
• is a root folder and not allowed as cache dir
• must resolve to an absolute directory

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

Appendix: source

Thrown at cache/filecache/filecache_config.go:316

		c[k] = v
	}

	return c, nil
}

// Resolves :resourceDir => /myproject/resources etc., :cacheDir => ...
func resolveDirPlaceholder(fs afero.Fs, bcfg config.BaseConfig, placeholder string) (cacheDir string, isResource bool, err error) {
	switch strings.ToLower(placeholder) {
	case ":resourcedir":
		return "", true, nil
	case ":cachedir":
		return bcfg.CacheDir, false, nil
	case ":project":
		return filepath.Base(bcfg.WorkingDir), false, nil
	}

	return "", false, fmt.Errorf("%q is not a valid placeholder (valid values are :cacheDir or :resourceDir)", placeholder)
}

View on GitHub (pinned to 52c9bd7908)