hubble-metrics configuration validation failed: %w

Error message

hubble-metrics configuration validation failed: %w

What it means

newValidatedConfig wraps the cell's Config.Validate() result. Any failure while parsing/validating the hubble-metrics configuration (unknown metric, bad option, conflicting plugins) is re-wrapped with this message. It is the cell-level aggregate error; the underlying cause (%w) names the actual problem.

Source

Thrown at pkg/hubble/metrics/cell/cell.go:74

	flags.String("hubble-metrics", def.Metrics, "List of Hubble metrics to enable.")
	flags.Bool("enable-hubble-open-metrics", def.EnableOpenMetrics, "Enable exporting hubble metrics in OpenMetrics format.")
	flags.String("hubble-metrics-server", def.MetricsServer, "Address to serve Hubble metrics on.")
	flags.String("hubble-dynamic-metrics-config-path", def.DynamicMetricConfigFilePath, "Filepath with dynamic configuration of hubble metrics.")
}

func (cfg Config) Validate() error {
	if cfg.DynamicMetricConfigFilePath != "" && len(cfg.Metrics) > 0 {
		return errors.New("cannot configure both static and dynamic Hubble metrics")
	}
	return nil
}

// ValidatedConfig is a config that is known to be valid.
type ValidatedConfig Config

func newValidatedConfig(c Config) (ValidatedConfig, error) {
	if err := c.Validate(); err != nil {
		return ValidatedConfig{}, fmt.Errorf("hubble-metrics configuration validation failed: %w", err)
	}
	return ValidatedConfig(c), nil
}

type params struct {
	cell.In

	Logger    *slog.Logger
	Lifecycle cell.Lifecycle
	JobGroup  job.Group

	GRPCServerMetrics *grpc_prometheus.ServerMetrics
	TLSConfigPromise  tlsConfigPromise

	Config ValidatedConfig
}

func newFlowProcessor(p params) (metrics.FlowProcessor, error) {

View on GitHub (pinned to ac7b90affa)

Solutions

Read the wrapped cause (%w) in the log to identify the specific invalid setting
Correct the --hubble-metrics / metrics list using the documented metric names and options
Validate the config with a matching Cilium version's docs before applying

Example fix

// before
hubble-metrics: "flows dns:query;labelsContext=bogus"
// after
hubble-metrics: "flow dns:query;labelsContext=source_pod"

Defensive patterns

Strategy: validation

Validate before calling

// Validate locally before applying to the cluster
cfg := api.ParseStaticMetricsConfig(strings.Fields(metricsList))
if _, err := api.NewRegistry(cfg /* ... */); err != nil {
    return fmt.Errorf("metrics config invalid: %w", err)
}

Prevention

Always read the wrapped %w cause — it names the exact bad entry
Keep hubble-metrics values in version control and review on upgrades
Test config changes in CI against the target Cilium version

When it happens

Trigger: Providing an invalid hubble-metrics config string via --hubble-metrics (or helm values) such that Config.Validate() returns an error, e.g. unknown metric name, invalid context option, or a plugin conflict like error 2922.

Common situations: Agent fails to start after editing hubble metrics in CiliumConfig; typos in metric names like `flows` instead of `flow`; invalid per-metric options after an upgrade changed accepted options.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

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