gohugoio/hugo · error

failed to compile cache buster

Error message

failed to compile cache buster %q: %w

What it means

Emitted by BuildConfig.CompileConfig while iterating build.CacheBusters. For each cache buster it calls CacheBuster.CompileConfig (error 279's source), and wraps any failure with the buster's `source` string. So this is the per-buster wrapper inside the loop, whereas 279 is the inner compile of the source regexp itself.

Solutions

1. Test the `source` value in a Go regexp tester or `go play`.
2. Remember Hugo cache busters use Go regexp syntax, not glob.
3. Remove the entry to confirm it is the culprit, then fix the pattern.

Example fix

# before
[build]
[[build.cacheBusters]]
source = "assets/(.*"
target = "$1"

# after
[build]
[[build.cacheBusters]]
source = "assets/(.*)"
target = "$1"

python3 - <<'PY'
import tomllib,re
cfg=tomllib.loads(open('hugo.toml').read())
for cb in cfg.get('build',{}).get('cacheBusters',[]):
    try: re.compile(cb['source'])
    except re.error as e: print(f"bad cacheBuster source {cb['source']!r}: {e}")
print("cacheBusters ok")
PY

When it happens

Trigger: A `[build]` config with `cacheBusters` whose `source` is an invalid Go regexp; a typo like an unbalanced parenthesis or quantifier on nothing.

Common situations: Hand-writing cache busters for the dev server / fingerprinting and getting regexp syntax wrong; copying a glob pattern where a regexp is expected.

Related errors

• failed to compile cache buster source
• cache dir contains unresolved placeholders
• failed to compile Redirect regexp
• failed to create file caches from configuration
• failed to decode filecache config

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

Appendix: source

Thrown at config/commonConfig.go:172

		}
	}
	if len(matchers) > 0 {
		return (func(cacheKey string) bool {
			for _, m := range matchers {
				if m(cacheKey) {
					return true
				}
			}
			return false
		}), nil
	}
	return nil, nil
}

func (b *BuildConfig) CompileConfig(logger loggers.Logger) error {
	for i, cb := range b.CacheBusters {
		if err := cb.CompileConfig(logger); err != nil {
			return fmt.Errorf("failed to compile cache buster %q: %w", cb.Source, err)
		}
		b.CacheBusters[i] = cb
	}
	return nil
}

func DecodeBuildConfig(cfg Provider) BuildConfig {
	m := cfg.GetStringMap("build")

	b := defaultBuild.clone()
	if m == nil {
		return b
	}

	// writeStats was a bool <= v0.115.0.
	if writeStats, ok := m["writestats"]; ok {
		if bb, ok := writeStats.(bool); ok {
			m["buildstats"] = BuildStats{Enable: bb}

View on GitHub (pinned to 52c9bd7908)