cilium/cilium · error

plugin %s conflicts with plugin %s

Error message

plugin %s conflicts with plugin %s

What it means

validateAndCreateHandlerLocked checks plugin-declared conflicts before instantiating a metric handler. If a plugin implements PluginConflicts and lists another plugin that is already registered under the same metrics registry, registration is refused. This prevents two mutually exclusive metric handlers (e.g. two flow metrics with overlapping Prometheus names) from being enabled simultaneously.

Source

Thrown at pkg/hubble/metrics/api/registry.go:85

	return InitHandlers(logger, registry, &enabledHandlers)
}

func (r *Registry) ValidateAndCreateHandler(metricsConfig *MetricConfig, metricNames *map[string]*MetricConfig) (*NamedHandler, error) {
	r.mutex.Lock()
	defer r.mutex.Unlock()
	return r.validateAndCreateHandlerLocked(metricsConfig, metricNames)
}

func (r *Registry) validateAndCreateHandlerLocked(metricsConfig *MetricConfig, metricNames *map[string]*MetricConfig) (*NamedHandler, error) {
	plugin, ok := r.handlers[metricsConfig.Name]
	if !ok {
		return nil, &errMetricNotExist{metricsConfig.Name}
	}

	if cp, ok := plugin.(PluginConflicts); ok {
		for _, conflict := range cp.ConflictingPlugins() {
			if _, conflictExists := (*metricNames)[conflict]; conflictExists {
				return nil, fmt.Errorf("plugin %s conflicts with plugin %s", metricsConfig.Name, conflict)
			}
		}
	}

	h := NamedHandler{
		Name:         metricsConfig.Name,
		Handler:      plugin.NewHandler(),
		MetricConfig: metricsConfig,
	}

	return &h, nil
}

type errMetricNotExist struct {
	name string
}

func (e *errMetricNotExist) Error() string {

View on GitHub (pinned to ac7b90affa)

Solutions

1. Remove one of the two conflicting metric configurations from the hubble-metrics list
2. Reconfigure one metric with options so it no longer declares the conflict (e.g. use distinct sourceContext settings)
3. Check the plugin's ConflictingPlugins() implementation in pkg/hubble/metrics to see exactly which names clash

Example fix

// before
metrics: ["flow", "flow:sourceContext=workload"]
// after
metrics: ["flow:sourceContext=res-bytes,destinationContext=workload"]

// Deduplicate metric names before configuring
seen := map[string]bool{}
for _, m := range strings.Fields(metricsConfig) {
    name := strings.SplitN(m, ":", 2)[0]
    if seen[name] { return fmt.Errorf("duplicate/conflicting metric: %s", name) }
    seen[name] = true
}

When it happens

Trigger: Configuring two conflicting metrics at once, e.g. `metrics: ["flow","flow:sourceContext=workload"]` variants, or any pair where one plugin's ConflictingPlugins() includes the other's registered name in (*metricNames).

Common situations: Appending a new metric to the hubble-metrics list without realizing it conflicts with an existing one (e.g. duplicate flow metrics, dns + a conflicting variant); merging helm values that each add a metric.

Related errors

• unable to initialize metric '%s': %w
• unknown context '%s'
• invalid labelsContext value: %s
• hubble-metrics configuration validation failed: %w
• failed to setup hubble metrics: %w

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