gohugoio/hugo · error

invalid deployment.matchers.pattern

Error message

invalid deployment.matchers.pattern: %v

What it means

DecodeConfig (deploy/deployconfig/deployConfig.go:165) compiles each [[deployment.matchers]] Pattern as a Go regexp (m.Re). This wraps regexp.Compile failure. Matchers attach Cache-Control/Content-Type/etc. metadata to uploaded files whose paths match.

Solutions

1. Treat matchers.pattern as a regex, not a glob: use '.*' for 'any' and anchor with '^'/'$' as needed.
2. Validate the pattern with regexp.Compile before adding it.
3. Escape literal dots/metacharacters ('\.').
4. Balance all parentheses and character classes.

Example fix

# before
[[deployment.matchers]]
pattern = "*.css"          # glob syntax, invalid regex
cacheControl = "public"

# after
[[deployment.matchers]]
pattern = ".*\.css$"
cacheControl = "public"

import "regexp"

func ValidateMatcherPattern(pattern string) error {
    if _, err := regexp.Compile(pattern); err != nil {
        return fmt.Errorf("matchers.pattern %q: %w", pattern, err)
    }
    return nil
}

if _, err := deployconfig.DecodeConfig(cfg); err != nil {
    return err
}

When it happens

Trigger: A [[deployment.matchers]] entry whose `pattern` is invalid regex, e.g. an unbalanced parenthesis, dangling quantifier, or glob-style '*' used where regex '.*' is required.

Common situations: Writing a glob pattern ('*.css') in a matchers.pattern, which must be a regex; copy-pasting a glob from elsewhere; unclosed character class.

Related errors

• invalid deployment.orderings.pattern
• deployment target not found
• empty deployment matcher
• empty deployment target
• failed to compile cache buster target

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

Appendix: 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 52c9bd7908)