jaegertracing/jaeger · error

cannot initialize admin server: %w

Error message

cannot initialize admin server: %w

What it means

This error is returned from flags.Start() when s.Admin.initFromViper(v, s.Logger) fails to configure the admin server (the health-check + metrics HTTP server on port 14269 by default). Initialization parses the admin-related viper keys (host/port, health-check settings) and prepares the HTTP mux; any failure there aborts service startup with this wrapped error.

Source

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

	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())
	}

	if err := s.Admin.Serve(); err != nil {
		return fmt.Errorf("cannot start the admin server: %w", err)
	}

	return nil

View on GitHub (pinned to 806f444784)

Solutions

1. Correct the `jaeger.admin` section of your config (valid host:port, e.g. :14269) and restart
2. Run with the default admin settings by removing jaeger.admin overrides from the config
3. Check the wrapped `%w` cause in the log to see exactly which admin option was rejected
4. Compare your config keys against the admin flags documented for your Jaeger version

Example fix

// before (config.yaml)
jaeger:
  admin:
    http:
      host-port: "14269abc"
// after
jaeger:
  admin:
    http:
      host-port: ":14269"

// Pre-validate admin settings before Start
hostPort := v.GetString("jaeger.admin.http.host-port")
if hostPort != "" {
    if _, _, err := net.SplitHostPort(hostPort); err != nil {
        return fmt.Errorf("invalid jaeger.admin.http.host-port %q: %w", hostPort, err)
    }
}

if err := svc.Start(v); err != nil {
    if strings.Contains(err.Error(), "cannot initialize admin server") {
        // inspect wrapped cause via errors.Unwrap / %v for the bad admin key
    }
    return err
}

When it happens

Trigger: Calling flags.Start() where the viper config contains an invalid admin-server setting (e.g. non-numeric or out-of-range jaeger.admin.http.host-port, bad health-status values) that initFromViper rejects.

Common situations: Kubernetes/YAML config with a malformed `jaeger.admin.http.host-port`; port set as a string with extra characters; conflicting flags bound into viper; config produced for a different Jaeger release with a renamed admin option.

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
• failed to create admin server: %w
• cannot load config file: %w
• cannot create metrics factory: %w
• failed to initialize storage '%s': %w

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