jaegertracing/jaeger · error

cannot create metrics factory: %w

Error message

cannot create metrics factory: %w

What it means

This error wraps any failure from metricsBuilder.CreateMetricsFactory("") while the Jaeger service is starting up. The metrics builder reads the `jaeger.metrics` configuration section from viper and instantiates the chosen metrics backend (prometheus, expvar, or none). If the backend cannot be constructed — typically because its configuration is invalid or the registry cannot be created — the process refuses to start and returns this wrapped error.

Source

Thrown at cmd/internal/flags/service.go:85

	sFlags := new(SharedFlags).InitFromViper(v)
	newProdConfig := zap.NewProductionConfig()
	newProdConfig.Sampling = nil
	logger, err := sFlags.NewLogger(newProdConfig)
	if err != nil {
		return fmt.Errorf("cannot create logger: %w", err)
	}
	s.Logger = logger
	grpclog.SetLoggerV2(zapgrpc.NewLogger(
		logger.WithOptions(
			zap.AddCallerSkip(5), // ensure the actual caller:lineNo is shown
		),
	))

	metricsBuilder := new(metricsbuilder.Builder).InitFromViper(v)
	metricsFactory, err := metricsBuilder.CreateMetricsFactory("")
	if err != nil {
		return fmt.Errorf("cannot create metrics factory: %w", err)
	}
	s.MetricsFactory = metricsFactory

	if err = s.Admin.initFromViper(v, s.Logger); err != nil {
		return fmt.Errorf("cannot initialize admin server: %w", err)
	}
	if h := metricsBuilder.Handler(); h != nil {
		route := metricsBuilder.HTTPRoute
		s.Logger.Info("Mounting metrics handler on admin server", zap.String("route", route))
		s.Admin.Handle(route, h)
	}

	// Mount expvar routes on different backends
	if metricsBuilder.Backend != "expvar" {
		s.Logger.Info("Mounting expvar handler on admin server", zap.String("route", "/debug/vars"))
		s.Admin.Handle("/debug/vars", expvar.Handler())
	}

View on GitHub (pinned to 806f444784)

Solutions

1. Fix the `jaeger.metrics` section in your config so the chosen backend (prometheus/expvar/none) has only valid options for your Jaeger version
2. Set jaeger.metrics.backend to `none` (or omit it) to start without a metrics backend and confirm the rest of the service boots
3. Read the wrapped `%w` cause in the log line — it names the underlying metrics-backend error and points at the bad field
4. Upgrade/downgrade Jaeger so the metrics config schema matches what your config file was written for

Example fix

// before (config.yaml)
jaeger:
  metrics:
    backend: promethus
    prometheus:
      timerType: bogus
// after
jaeger:
  metrics:
    backend: prometheus
    prometheus:
      timerType: histogram

import "github.com/jaegertracing/jaeger/cmd/internal/flags"
// Before Start, pre-parse and sanity-check the metrics config
var mCfg metricsbuilder.Config
if err := v.UnmarshalKey("jaeger.metrics", &mCfg); err != nil {
    return fmt.Errorf("invalid jaeger.metrics config: %w", err)
}
switch mCfg.Backend {
case "", "prometheus", "expvar", "none":
    // ok
default:
    return fmt.Errorf("unsupported jaeger.metrics.backend: %q", mCfg.Backend)
}

if err := svc.Start(v); err != nil {
    var wrapped interface{ Unwrap() error }
    if errors.As(err, &target) { /* inspect underlying metrics backend error */ }
    log.Fatalf("startup failed: %v", err)
}

When it happens

Trigger: Calling flags.Start() (via the jaeger all-in-one or collector binary) with a metrics config that names a backend the builder fails to instantiate, e.g. jaeger.metrics.backend=prometheus with invalid fields, or an unknown/unsupported backend value.

Common situations: Operators set a metrics backend in the YAML/CLI config with a typo or an option belonging to a different Jaeger version; the Prometheus factory fails while connecting to or constructing its registry; an empty backend string combined with malformed sub-config.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• unknown metrics backend specified
• cannot load config file: %w
• cannot initialize admin server: %w
• failed to initialize storage '%s': %w
• cannot read embedded all-in-one configuration: %w

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/c979b2ec79e87e93. Report an issue: GitHub.