What causes "invalid deployment.matchers.pattern: %v" in gohugoio/hugo?

Fix the regex: patterns must be valid Go RE2, e.g. use `^.+\.(js|css)$` instead of glob syntax like `*.js`.

invalid deployment.matchers.pattern: %v

Error message

invalid deployment.matchers.pattern: %v

What it means

Raised at deployConfig.go:167 when `regexp.Compile(m.Pattern)` fails for a `deployment.matchers` entry. Matcher patterns are Go RE2 regular expressions matched against remote paths; a syntactically invalid regex makes the whole deployment config decode fail fast rather than silently skipping the matcher.

Source

Thrown at deploy/deployconfig/deployConfig.go:167

		dcfg.Workers = 10
	}

	for _, tgt := range dcfg.Targets {
		if *tgt == (Target{}) {
			return dcfg, errors.New("empty deployment target")
		}
		if err := tgt.ParseIncludeExclude(); err != nil {
			return dcfg, err
		}
	}
	var err error
	for _, m := range dcfg.Matchers {
		if *m == (Matcher{}) {
			return dcfg, errors.New("empty deployment matcher")
		}
		m.Re, err = regexp.Compile(m.Pattern)
		if err != nil {
			return dcfg, fmt.Errorf("invalid deployment.matchers.pattern: %v", err)
		}
	}
	for _, o := range dcfg.Order {
		re, err := regexp.Compile(o)
		if err != nil {
			return dcfg, fmt.Errorf("invalid deployment.orderings.pattern: %v", err)
		}
		dcfg.Ordering = append(dcfg.Ordering, re)
	}

	return dcfg, nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Fix the regex: patterns must be valid Go RE2, e.g. use `^.+\.(js|css)$` instead of glob syntax like `*.js`.
Remove PCRE-only constructs (lookahead/behind, backreferences) — RE2 does not support them; rewrite with alternation.
In TOML, prefer single-quoted literal strings (`pattern = '^.+\.(js|css)$'`) to avoid double-escaping backslashes.
Test the pattern at https://go.dev/play or with `regexp.MustCompile` in a scratch Go file.

Example fix

# before
[[deployment.matchers]]
pattern = "*.js"

# after
[[deployment.matchers]]
pattern = '^.+\.js$'

Defensive patterns

Strategy: validation

Validate before calling

for i, m := range cfg.Deployment.Matchers {
    if _, err := regexp.Compile(m.Pattern); err != nil {
        return fmt.Errorf("deployment.matchers[%d] pattern %q: %w", i, m.Pattern, err)
    }
}

Try / catch

if err := deployConfig.Validate(); err != nil {
    var syntaxErr *syntax.Error
    if errors.As(err, &syntaxErr) {
        log.Fatalf("bad matcher regexp: %v", syntaxErr)
    }
    return err
}

Prevention

Matcher patterns are Go RE2 regexps, not globs — test them with regexp.Compile or regex101 (Golang flavor) first
Escape literal dots and other metacharacters (e.g. `\\.html$` not `.html$`)
Run `hugo deploy --dryRun` in CI so a bad pattern fails before touching the target

When it happens

Trigger: `hugo deploy` with a `[[deployment.matchers]]` `pattern` that is not valid RE2 — unbalanced parentheses/brackets, dangling `*` or `+`, or RE2-unsupported constructs like backreferences (`\1`) and lookaheads (`(?=...)`).

Common situations: Writing a glob (`*.js`) where a regex is expected; porting PCRE patterns with lookahead/backreferences that RE2 rejects; TOML single-vs-double-quote escaping mistakes turning `\.` into an invalid sequence.

Related errors

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