jaegertracing/jaeger · error

unknown metrics backend specified

Error message

unknown metrics backend specified

What it means

errUnknownBackend is returned by the metrics Builder (CreateMetricsFactory and TestBuilder) when the configured Backend field does not name a metrics backend this Jaeger build knows how to create. Jaeger supports a fixed set of backends (e.g. "prometheus", "none"); anything else fails at factory creation time before any metrics are recorded. It prevents silent fallback to a backend the operator did not ask for.

Source

Thrown at internal/metrics/metricsbuilder/builder.go:27

	"flag"
	"net/http"

	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promhttp"
	"github.com/spf13/viper"

	"github.com/jaegertracing/jaeger/internal/metrics"
	jprom "github.com/jaegertracing/jaeger/internal/metrics/prometheus"
)

const (
	metricsBackend        = "metrics-backend"
	metricsHTTPRoute      = "metrics-http-route"
	defaultMetricsBackend = "prometheus"
	defaultMetricsRoute   = "/metrics"
)

var errUnknownBackend = errors.New("unknown metrics backend specified")

// Builder provides command line options to configure metrics backend used by Jaeger executables.
type Builder struct {
	Backend   string
	HTTPRoute string // endpoint name to expose metrics, e.g. for scraping
	handler   http.Handler
}

// AddFlags adds flags for Builder.
func AddFlags(flags *flag.FlagSet) {
	flags.String(
		metricsBackend,
		defaultMetricsBackend,
		"Defines which metrics backend to use for metrics reporting: prometheus or none",
	)
	flags.String(
		metricsHTTPRoute,
		defaultMetricsRoute,

View on GitHub (pinned to 806f444784)

Solutions

1. Set --metrics-backend to "prometheus" (the default) or another supported value listed in the builder tests/docs.
2. Check the flag value for typos and exact casing (values are matched literally, e.g. lowercase "prometheus").
3. Omit the flag entirely to use the defaultMetricsBackend "prometheus".
4. If a non-prometheus backend is genuinely needed, verify the Jaeger build/version includes it before upgrading expectations.

Example fix

// before
jaeger-collector --metrics-backend=prom
// after
jaeger-collector --metrics-backend=prometheus

switch backend {
case "", "prometheus", "none":
    // ok
default:
    return fmt.Errorf("unsupported --metrics-backend %q (use prometheus or none)", backend)
}

When it happens

Trigger: Builder.Backend is set to a misspelled or unsupported value (e.g. "prom", "Prometheus", "statsd") and CreateMetricsFactory (or TestBuilder during validation) is called; typically via the --metrics-backend flag.

Common situations: Typo in the --metrics-backend CLI flag or env var; copying config from an older Jaeger version whose supported backend names changed; assuming a backend (statsd, influxdb) exists when only prometheus/none are compiled in.

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

• cannot create metrics factory: %w
• 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/e440a50a61e6836a. Report an issue: GitHub.