cilium/cilium · error

no healthz status API server started

Error message

no healthz status API server started

What it means

registerAgentHealthHTTPService registers one healthz server job per configured address; 'available' counts how many jobs were actually registered. If zero servers were registered (nothing available to serve), the function returns this sentinel error instead of silently succeeding with no healthz endpoint.

Source

Thrown at daemon/healthz/agenthealth.go:122

			}()

			params.Logger.Info("Starting healthz status API server", logfields.Address, addr)
			if err := srv.Serve(ln); errors.Is(err, http.ErrServerClosed) {
				params.Logger.Info("healthz status API server shutdown", logfields.Address, addr)
			} else if err != nil {
				params.Logger.Error("Error serving healthz status API server",
					logfields.Address, addr,
					logfields.Error, err,
				)
				return fmt.Errorf("failed to start healthz status API server: %w", err)
			}

			return nil
		}))
	}

	if available <= 0 {
		return fmt.Errorf("no healthz status API server started")
	}

	return nil
}

type agentHealthHandler struct {
	logger          *slog.Logger
	config          agentHealthConfig
	statusCollector status.StatusCollector
}

func (h *agentHealthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	requireK8sConnectivity := h.config.AgentHealthRequireK8sConnectivity
	if v := r.Header.Get("require-k8s-connectivity"); v != "" {
		res, err := strconv.ParseBool(v)
		if err != nil {
			h.logger.Warn("require-k8s-connectivity should be bool",
				logfields.Value, v,

View on GitHub (pinned to ac7b90affa)

Solutions

1. Ensure at least one agent healthz address/port is configured (agentHealthPort / healthz configuration in Helm values)
2. Verify the cell/job wiring registers the healthz server job in your Cilium version; check release notes for healthz config changes
3. Restart the agent after correcting configuration
4. If intentionally disabling healthz, remove/skip the registration call instead of registering zero servers

if len(healthzListenAddrs) == 0 {
	return errors.New("no healthz listen addresses configured; set agent healthz port/address")
}

if err := registerAgentHealthHTTPService(params, ...); err != nil {
	if strings.Contains(err.Error(), "no healthz status API server started") {
		log.Warn("healthz disabled by configuration; skipping")
	}
	return err
}

When it happens

Trigger: Calling registerAgentHealthHTTPService when the set of configured healthz addresses is empty or all candidates were skipped, so no job was added and available <= 0.

Common situations: Misconfigured or missing agent healthz listener configuration in Helm values/ConfigMap; feature flags disabling all healthz listeners while the registration path is still invoked; wiring/registration bug after a version upgrade.

Related errors

• Kubernetes client not configured, cannot continue
• KVStore client not configured, cannot continue
• egress gateway is not supported in combination with the Cili
• no listener configured
• failed to init and validate daemon config: %w

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/590d7d736c4cb579. Report an issue: GitHub.