caddyserver/caddy · error

server %s: setting up route matchers: %v

Error message

server %s: setting up route matchers: %v

What it means

Automatic HTTPS phase 1 starts by provisioning all route matchers (ProvisionMatchers) for every server, because host matchers must be readable to determine which domains need certificates. If any matcher module fails to load or provision, this error names the server and wraps the cause. It runs before any cert decisions are made.

Source

Thrown at modules/caddyhttp/autohttps.go:111

	// Sort server names to ensure deterministic iteration.
	// This prevents race conditions where the order of server processing
	// could affect which server gets assigned the HTTP->HTTPS redirect listener.
	srvNames := make([]string, 0, len(app.Servers))
	for name := range app.Servers {
		srvNames = append(srvNames, name)
	}
	slices.Sort(srvNames)
	for _, srvName := range srvNames {
		srv := app.Servers[srvName]
		// as a prerequisite, provision route matchers; this is
		// required for all routes on all servers, and must be
		// done before we attempt to do phase 1 of auto HTTPS,
		// since we have to access the decoded host matchers the
		// handlers will be provisioned later
		if srv.Routes != nil {
			err := srv.Routes.ProvisionMatchers(ctx)
			if err != nil {
				return fmt.Errorf("server %s: setting up route matchers: %v", srvName, err)
			}
		}

		// prepare for automatic HTTPS
		if srv.AutoHTTPS == nil {
			srv.AutoHTTPS = new(AutoHTTPSConfig)
		}
		if srv.AutoHTTPS.Disabled {
			logger.Info("automatic HTTPS is completely disabled for server", zap.String("server_name", srvName))
			continue
		}

		// skip if all listeners use the HTTP port
		if !srv.listenersUseAnyPortOtherThan(app.httpPort()) {
			logger.Warn("server is listening only on the HTTP port, so no automatic HTTPS will be applied to this server",
				zap.String("server_name", srvName),
				zap.Int("http_port", app.httpPort()),
			)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped matcher error and fix that matcher (module ID, regexp syntax, options)
2. Rebuild with the required plugin if the matcher comes from a custom module
3. Iterate with `caddy validate --config` — matcher provisioning is exercised there too

Example fix

// before
{"match":[{"host":["example.com"}],"path":["*["]}
// after
{"match":[{"host":["example.com"}],"path":["/*"]}

if err := caddy.Validate(cfgJSON); err != nil { return err } // provisions matchers via auto-HTTPS path

When it happens

Trigger: Any matcher module error under servers.<name>.routes: unknown matcher module (missing plugin), malformed matcher JSON, or a matcher whose Provision fails (e.g. invalid regexp in path matcher, bad ACME match values).

Common situations: Custom matcher plugins not compiled in; regex syntax errors in path_regexp; migrating configs where a matcher option was renamed between versions.

Related errors

• loading new config: %v
• loading storage module: %v
• server %s: %v
• server %s: setting up route handlers: %v
• server %s: setting up error handling routes: %v

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