gohugoio/hugo · error

failed to compile cache buster %q: %w

Error message

failed to compile cache buster %q: %w

What it means

Raised by BuildConfig.CompileConfig in Hugo when one of the `build.cachebusters` entries fails to compile. Each CacheBuster carries a Source regexp (and a Target regexp compiled later); this wrapper error surfaces which cache buster entry is broken, wrapping the underlying compile error (typically the Source regexp failing regexp.Compile in CacheBuster.CompileConfig at config/commonConfig.go:411).

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 8a468df065)

Solutions

1. Fix the `source` value of the named cache buster in `[[build.cachebusters]]` so it is a valid Go RE2 regexp — the error message quotes the offending pattern.
2. Escape regexp metacharacters in literal paths (e.g. `\.` for dots) and remember `source` is a regexp, not a glob.
3. Remove PCRE-only constructs (lookarounds, backreferences); test the pattern at https://go.dev/play/ with regexp.Compile or on regex101 with the Golang flavor.

Example fix

# before (hugo.toml)
[[build.cachebusters]]
source = "assets/*.(js"
target = "(js|scss)"

# after
[[build.cachebusters]]
source = "assets/.*\\.(js|scss)$"
target = "(js|scss)"

// Validate cachebuster 'source' regexps before building config
for _, cb := range cfg.Build.CacheBusters {
    if _, err := regexp.Compile(cb.Source); err != nil {
        return fmt.Errorf("invalid cachebuster source %q: %w", cb.Source, err)
    }
}

cfg, err := allconfig.LoadConfig(...)
if err != nil {
    var msg = err.Error()
    if strings.Contains(msg, "failed to compile cache buster") {
        // report offending pattern to the user; do not proceed with build
    }
    return err
}

When it happens

Trigger: Defining `[[build.cachebusters]]` in hugo.toml with an invalid Go (RE2) regular expression in the `source` field, e.g. `source = "assets/*.(js"` (unclosed group) or using PCRE-only syntax like lookaheads `(?=...)`, which Go's regexp package rejects. The error fires during config compilation at startup of `hugo` or `hugo server`.

Common situations: Copying cache buster examples and treating `source` as a glob instead of a regexp (e.g. writing `assets/**.js`); using lookahead/lookbehind or backreferences from PCRE which RE2 does not support; unescaped special characters like `(`, `[`, or `+` in file paths; typos introduced while customizing the default cachebusters from Hugo docs.

Related errors

• failed to compile cache buster source %q: %w
• failed to compile cache buster target %q: %w
• failed to compile Redirect regexp %q: %w
• failed to compile whitelist pattern %q: %w
• no modules loaded (need at least the main module)

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/952cac276d6d9840.json. Report an issue: GitHub ↗.