{"record":{"id":"e440a50a61e6836a","repo":"jaegertracing/jaeger","slug":"unknown-metrics-backend-specified","errorCode":null,"errorMessage":"unknown metrics backend specified","messagePattern":"unknown metrics backend specified","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/metrics/metricsbuilder/builder.go","lineNumber":27,"sourceCode":"\t\"flag\"\n\t\"net/http\"\n\n\t\"github.com/prometheus/client_golang/prometheus\"\n\t\"github.com/prometheus/client_golang/prometheus/promhttp\"\n\t\"github.com/spf13/viper\"\n\n\t\"github.com/jaegertracing/jaeger/internal/metrics\"\n\tjprom \"github.com/jaegertracing/jaeger/internal/metrics/prometheus\"\n)\n\nconst (\n\tmetricsBackend        = \"metrics-backend\"\n\tmetricsHTTPRoute      = \"metrics-http-route\"\n\tdefaultMetricsBackend = \"prometheus\"\n\tdefaultMetricsRoute   = \"/metrics\"\n)\n\nvar errUnknownBackend = errors.New(\"unknown metrics backend specified\")\n\n// Builder provides command line options to configure metrics backend used by Jaeger executables.\ntype Builder struct {\n\tBackend   string\n\tHTTPRoute string // endpoint name to expose metrics, e.g. for scraping\n\thandler   http.Handler\n}\n\n// AddFlags adds flags for Builder.\nfunc AddFlags(flags *flag.FlagSet) {\n\tflags.String(\n\t\tmetricsBackend,\n\t\tdefaultMetricsBackend,\n\t\t\"Defines which metrics backend to use for metrics reporting: prometheus or none\",\n\t)\n\tflags.String(\n\t\tmetricsHTTPRoute,\n\t\tdefaultMetricsRoute,","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/internal/metrics/metricsbuilder/builder.go#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --metrics-backend to \"prometheus\" (the default) or another supported value listed in the builder tests/docs.","Check the flag value for typos and exact casing (values are matched literally, e.g. lowercase \"prometheus\").","Omit the flag entirely to use the defaultMetricsBackend \"prometheus\".","If a non-prometheus backend is genuinely needed, verify the Jaeger build/version includes it before upgrading expectations."],"exampleFix":"// before\njaeger-collector --metrics-backend=prom\n// after\njaeger-collector --metrics-backend=prometheus","handlingStrategy":"validation","validationCode":"switch backend {\ncase \"\", \"prometheus\", \"none\":\n    // ok\ndefault:\n    return fmt.Errorf(\"unsupported --metrics-backend %q (use prometheus or none)\", backend)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only pass documented backend names to --metrics-backend.","Omit the flag to accept the prometheus default.","Add a startup config self-check that validates backend names before deploying."],"tags":["config","metrics","startup"],"backgroundTag":"invalid-config-value","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}