What causes "no metrics registry found" in caddyserver/caddy?

Add the metrics handler to your server's route handling (global_metrics handler or 'metrics' directive in each site) so the registry is initialized

caddyserver/caddy · error

no metrics registry found

Error message

no metrics registry found

What it means

AdminMetrics.Provision fails when ctx.GetMetricsRegistry() returns nil while provisioning the 'admin.api.metrics' module, which serves Prometheus metrics on the admin endpoint. The registry is created by the metrics module (metrics.Metrics Provision) registering its registry into the context; if that has not happened, the admin metrics module cannot build its handler and refuses to start.

Source

Thrown at modules/metrics/adminmetrics.go:53

type AdminMetrics struct {
	registry *prometheus.Registry

	metricsHandler http.Handler
}

// CaddyModule returns the Caddy module information.
func (AdminMetrics) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "admin.api.metrics",
		New: func() caddy.Module { return new(AdminMetrics) },
	}
}

// Provision -
func (m *AdminMetrics) Provision(ctx caddy.Context) error {
	m.registry = ctx.GetMetricsRegistry()
	if m.registry == nil {
		return errors.New("no metrics registry found")
	}
	m.metricsHandler = createMetricsHandler(nil, false, m.registry)
	return nil
}

// Routes returns a route for the /metrics endpoint.
func (m *AdminMetrics) Routes() []caddy.AdminRoute {
	return []caddy.AdminRoute{{Pattern: "/metrics", Handler: caddy.AdminHandlerFunc(m.serveHTTP)}}
}

func (m *AdminMetrics) serveHTTP(w http.ResponseWriter, r *http.Request) error {
	m.metricsHandler.ServeHTTP(w, r)
	return nil
}

// Interface guards
var (
	_ caddy.Provisioner = (*AdminMetrics)(nil)

View on GitHub (pinned to 50e54ee279)

Solutions

Add the metrics handler to your server's route handling (global_metrics handler or 'metrics' directive in each site) so the registry is initialized
If running a custom build, ensure the standard imports (caddy/modules/standard) include modules/metrics
Run caddy validate on the config to confirm module wiring before starting
If you only need app-level metrics via admin endpoint, prefer enabling server_metrics via the documented 'servers > metrics' config rather than hand-inserting admin.api.metrics

Defensive patterns

Strategy: validation

Prevention

Always pair the admin metrics endpoint with the metrics handler in server config
Use caddy validate before deploying configs that touch admin.api modules
Keep custom builds including modules/metrics via standard imports

When it happens

Trigger: Loading a config that includes the admin.api.metrics module (or enabling the /metrics admin endpoint) without the 'http.handlers.metrics' server-timing/metrics module having initialized the registry first; custom builds where the metrics module is not compiled in; module provisioning order edge cases.

Common situations: Manually adding admin.api.metrics to JSON config without the corresponding server metrics handler; using a stripped-down custom Caddy binary that omits the standard metrics module; config ordering issues in embedded caddy.Server runs.

Related errors

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