invalid regexp name (must contain only word characters): %s

Error message

invalid regexp name (must contain only word characters): %s

What it means

MatchRegexp.Validate requires the optional `name` of a regexp matcher to match \w+ (letters, digits, underscore only, non-empty). The name becomes the namespace for {http.regexp.<name>.captures...} placeholders, so characters like '.', '-', '/' or spaces would break placeholder keys and are rejected.

Source

Thrown at modules/caddyhttp/matchers.go:1601

	Pattern string `json:"pattern"`

	compiled *regexp.Regexp
}

// Provision compiles the regular expression.
func (mre *MatchRegexp) Provision(caddy.Context) error {
	re, err := regexp.Compile(mre.Pattern)
	if err != nil {
		return fmt.Errorf("compiling matcher regexp %s: %v", mre.Pattern, err)
	}
	mre.compiled = re
	return nil
}

// Validate ensures mre is set up correctly.
func (mre *MatchRegexp) Validate() error {
	if mre.Name != "" && !wordRE.MatchString(mre.Name) {
		return fmt.Errorf("invalid regexp name (must contain only word characters): %s", mre.Name)
	}
	return nil
}

// Match returns true if input matches the compiled regular
// expression in mre. It sets values on the replacer repl
// associated with capture groups, using the given scope
// (namespace).
func (mre *MatchRegexp) Match(input string, repl *caddy.Replacer) bool {
	matches := mre.compiled.FindStringSubmatch(input)
	if matches == nil {
		return false
	}

	// save all capture groups, first by index
	for i, match := range matches {
		keySuffix := "." + strconv.Itoa(i)
		if mre.Name != "" {

View on GitHub (pinned to 50e54ee279)

Solutions

Rename to word characters only: use v1 not v.1, my_name not my-name.
Keep the name short and unique per matcher if you rely on its placeholders.
If placeholders are not used, you may omit the name entirely.

Example fix

// before (Caddyfile)
@m path_regexp my-name ^/x(.*)

// after
@m path_regexp my_name ^/x(.*)

Defensive patterns

Strategy: validation

Validate before calling

import "regexp"

var wordRE = regexp.MustCompile(`^\w+$`)

func validRegexpName(name string) bool {
	return name == "" || wordRE.MatchString(name)
}

Prevention

Name regexp matchers with [A-Za-z0-9_] only.
Use snake_case, not kebab-case or dotted names.
Omit the name if you never read its placeholders.

When it happens

Trigger: header_regexp foo.bar UserAgent ... (dot), path_regexp my-name ... (hyphen), name with a space or slash, or an empty-after-trimming name.

Common situations: Naming capture groups after hostnames or URLs (myapp.example.com); kebab-case habit from other directives; JSON configs where the name field is auto-filled from an ID.

Related errors

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/927f24584b112ba9. Report an issue: GitHub.