caddyserver/caddy · error

provisioning admin router module %s: %v

Error message

provisioning admin router module %s: %v

What it means

While building the admin endpoint's route table, Caddy iterates all modules in the 'admin.api' namespace and calls Provision on those implementing Provisioner. If any such module fails provisioning, startup aborts with this wrapper including the module ID and the underlying error. The wrapped error (e.g. 'no metrics registry found') carries the real cause.

Source

Thrown at admin.go:283

	addRoute("/stop", handlerLabel, AdminHandlerFunc(handleStop))

	// register debugging endpoints
	addRouteWithMetrics("/debug/pprof/", handlerLabel, http.HandlerFunc(pprof.Index))
	addRouteWithMetrics("/debug/pprof/cmdline", handlerLabel, http.HandlerFunc(pprof.Cmdline))
	addRouteWithMetrics("/debug/pprof/profile", handlerLabel, http.HandlerFunc(pprof.Profile))
	addRouteWithMetrics("/debug/pprof/symbol", handlerLabel, http.HandlerFunc(pprof.Symbol))
	addRouteWithMetrics("/debug/pprof/trace", handlerLabel, http.HandlerFunc(pprof.Trace))
	addRouteWithMetrics("/debug/vars", handlerLabel, expvar.Handler())

	// register third-party module endpoints
	for _, m := range GetModules("admin.api") {
		router := m.New().(AdminRouter)

		// provision the router before registering its routes, so
		// handlers have access to all provisioned state
		if provisioner, ok := router.(Provisioner); ok {
			if err := provisioner.Provision(ctx); err != nil {
				return adminHandler{}, fmt.Errorf("provisioning admin router module %s: %v", m.ID, err)
			}
		}

		for _, route := range router.Routes() {
			addRoute(route.Pattern, handlerLabel, route.Handler)
		}
	}

	return muxWrap, nil
}

// allowedOrigins returns a list of origins that are allowed.
// If admin.Origins is nil (null), the provided listen address
// will be used as the default origin. If admin.Origins is
// empty, no origins will be allowed, effectively bricking the
// endpoint for non-unix-socket endpoints, but whatever.
func (admin AdminConfig) allowedOrigins(addr NetworkAddress) []*url.URL {
	uniqueOrigins := make(map[string]struct{})

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the '%s: %v' suffix — the module ID names the failing module and the inner error the cause; fix that module's config
2. Remove or correct the offending admin.api module from the config
3. For plugins, check compatibility with your Caddy version and rebuild xcaddy build with matching versions
4. Validate with caddy validate --config to catch it before restart

if err := adminConfigProvision(cfg); err != nil {
    var apiErr caddy.APIError
    if errors.As(err, &apiErr) {
        log.Printf("admin module provisioning failed: status=%d err=%v", apiErr.HTTPStatus, apiErr.Err)
    }
    // fall back to last-known-good config
}

When it happens

Trigger: Any admin.api.* module whose Provision returns an error: admin.api.metrics with a missing registry, third-party admin routers with invalid config, custom plugins registered under admin.api failing to provision.

Common situations: Installing a third-party admin API plugin with a bad or missing config block; enabling the metrics admin endpoint in a config that doesn't initialize the registry; plugin version incompatibility after upgrading Caddy.

Related errors

• no metrics registry found
• encoding new config: %v
• loading new config: %v
• starting caddy administration endpoint: %v
• loading template extensions: %v

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