caddyserver/caddy · error

no metrics registry found

Error message

no metrics registry found

What it means

Metrics.Provision for the 'http.handlers.metrics' module fails when ctx.GetMetricsRegistry() returns nil. In normal operation the registry is initialized early by the Caddy runtime (initMetrics) once per process; seeing nil usually means the runtime was not bootstrapped correctly — most commonly in tests, embedded use of the caddy package, or library consumers calling Provision outside a normal caddy run.

Source

Thrown at modules/metrics/metrics.go:68

		ID:  "http.handlers.metrics",
		New: func() caddy.Module { return new(Metrics) },
	}
}

type zapLogger struct {
	zl *zap.Logger
}

func (l *zapLogger) Println(v ...any) {
	l.zl.Sugar().Error(v...)
}

// Provision sets up m.
func (m *Metrics) Provision(ctx caddy.Context) error {
	log := ctx.Logger()
	registry := ctx.GetMetricsRegistry()
	if registry == nil {
		return errors.New("no metrics registry found")
	}
	m.metricsHandler = createMetricsHandler(&zapLogger{log}, !m.DisableOpenMetrics, registry)
	return nil
}

func parseCaddyfile(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error) {
	var m Metrics
	err := m.UnmarshalCaddyfile(h.Dispenser)
	return m, err
}

// UnmarshalCaddyfile sets up the handler from Caddyfile tokens. Syntax:
//
//	metrics [<matcher>] {
//	    disable_openmetrics
//	}
func (m *Metrics) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
	d.Next() // consume directive name

View on GitHub (pinned to 50e54ee279)

Solutions

1. In tests/library use, ensure caddy.Run(newCfg) or the normal startup path initializes the runtime before provisioning modules
2. For normal server use, simply start with caddy run — if it still fails, check that the binary is an unmodified build from this source tree
3. Report a bug upstream if reproducible with a stock config on a stock binary, since the registry should always be initialized by initMetrics

When it happens

Trigger: Adding the 'metrics' directive/handler in a config; unit tests that provision a Metrics module with a bare caddy.Context; embedding Caddy as a library and driving provisioning manually; unusual module-loading orders that skip metrics bootstrap.

Common situations: Writing Go tests against caddyhttp handlers that include the metrics module; third-party forks that changed runtime initialization; running provisioning pipelines twice in the same process with cleared global state.

Related errors

• no metrics registry found
• --input is required
• provisioning admin router module %s: %v
• loading new config: %v
• loading storage module: %v

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