jaegertracing/jaeger · error

failed to create admin server: %w

Error message

failed to create admin server: %w

What it means

During serveWithListener (invoked from Serve), the admin HTTP server is constructed via the httpserver package (with a recovery handler and no-op telemetry). If that constructor returns an error, it is wrapped as "failed to create admin server". This means the server object itself could not be built, before any listener bind attempt.

Source

Thrown at cmd/internal/flags/admin.go:122

	}

	return s.serveWithListener(l)
}

func (s *AdminServer) serveWithListener(l net.Listener) (err error) {
	s.logger.Info("Mounting health check on admin server", zap.String("route", "/"))
	s.mux.Handle("/", s.hc.Handler())
	version.RegisterHandler(s.mux, s.logger)
	s.registerPprofHandlers()
	recoveryHandler := recoveryhandler.NewRecoveryHandler(s.logger, true)
	s.server, err = s.serverCfg.ToServer(
		context.Background(),
		nil, // host
		telemetry.NoopSettings().ToOtelComponent(),
		recoveryHandler(s.mux),
	)
	if err != nil {
		return fmt.Errorf("failed to create admin server: %w", err)
	}
	errorLog, _ := zap.NewStdLogAt(s.logger, zapcore.ErrorLevel)
	s.server.ErrorLog = errorLog

	s.logger.Info("Starting admin HTTP server")
	started := make(chan struct{})
	s.stopped.Go(func() {
		close(started)
		err := s.server.Serve(l)
		if err != nil && !errors.Is(err, http.ErrServerClosed) {
			s.logger.Error("failed to serve", zap.Error(err))
			s.hc.SetUnavailable()
		}
	})
	<-started // wait for the server to start listening
	s.logger.Info("Admin server started", zap.String("http.host-port", l.Addr().String()))
	return nil
}

View on GitHub (pinned to 806f444784)

Solutions

1. Read the wrapped cause from the log for the constructor's exact complaint.
2. Re-check all --admin.http.* flags for invalid values (endpoint, TLS).
3. Reset admin flags to defaults to isolate which flag breaks creation.
4. Upgrade/align jaeger and its httpserver dependency versions.

Example fix

// before
--admin.http.host-port=:::99999  # invalid endpoint
// after
--admin.http.host-port=:14269

if err := adminFlags.Serve(); err != nil {
    if strings.Contains(err.Error(), "failed to create admin server") {
        // log wrapped cause and bail before retrying
    }
    log.Fatalf("admin server startup failed: %v", err)
}

When it happens

Trigger: The httpserver.New call inside serveWithListener returns non-nil err — e.g. invalid internal server configuration produced from flags (bad TLS settings already applied to serverCfg, invalid options) — causing server creation to abort.

Common situations: Malformed admin TLS config flowing into the server constructor; corrupted or incompatible configuration assembled in initFromViper; library version mismatch after upgrade changing constructor requirements.

Related errors

• cannot initialize admin server: %w
• server with TLS enabled can not use same host ports for gRPC
• unknown metrics backend specified
• error creating Elasticsearch client: %w
• failed to create Elasticsearch client: %w

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