--collector.netdev.device-blacklist and…

Error message

--collector.netdev.device-blacklist and --collector.netdev.device-exclude are mutually exclusive

What it means

This is the exclude-flag twin of the include conflict: --collector.netdev.device-blacklist is the deprecated alias of --collector.netdev.device-exclude. Supplying both with non-empty values makes NewNetDevCollector fail immediately with this mutual-exclusion error, preventing ambiguous filter configuration. Only the old flag alone triggers a deprecation warning and automatic migration.

Solutions

Drop the deprecated --collector.netdev.device-blacklist flag and keep only --collector.netdev.device-exclude.
Grep systemd units, container args, and config-management repos for `device-blacklist` and remove it everywhere.
Alternatively keep only the old flag (auto-migrated with a warning), then remove it before node_exporter 2.0.0.
Restart node_exporter; the collector will initialize cleanly.

Example fix

// before
node_exporter --collector.netdev.device-blacklist=veth.* --collector.netdev.device-exclude=lo
// after
node_exporter --collector.netdev.device-exclude=lo

Defensive patterns

Strategy: validation

Validate before calling

# Fail the deploy script if both exclude flags are present
if [[ -n "$BLACKLIST" && -n "$EXCLUDE" ]]; then
  echo "ERROR: device-blacklist and device-exclude are mutually exclusive" >&2
  exit 1
fi

Try / catch

c, err := NewNetDevCollector(logger)
if err != nil && strings.Contains(err.Error(), "mutually exclusive") {
    logger.Error("netdev exclude-flag conflict; remove deprecated device-blacklist", "err", err)
    os.Exit(2)
}

Prevention

Rename all device-blacklist usages to device-exclude in config management before upgrading.
Grep launch artifacts for `netdev.device-blacklist` (systemd units, Dockerfiles, helm values).
Treat any DEPRECATED warning in logs as a to-do: the paired-flag hard failure is one config layer away.
Pin and test the full command line used in production so flag conflicts surface before rollout.

When it happens

Trigger: Launching node_exporter with BOTH --collector.netdev.device-blacklist and --collector.netdev.device-exclude non-empty, e.g. `--collector.netdev.device-blacklist=veth.* --collector.netdev.device-exclude=lo`.

Common situations: Partial flag renames in automation: an updated Ansible recipe adds device-exclude while an older init script or Docker wrapper still appends device-blacklist; stale flags persisted in systemd drop-ins or environment-assembled command lines.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of prometheus/node_exporter@17ddd77c59 (2026-09-07). Data as JSON: /api/errors/d7d7ee20f8e50d8c. Report an issue: GitHub.

Appendix: source

Thrown at collector/netdev_common.go:69

}

// NewNetDevCollector returns a new Collector exposing network device stats.
func NewNetDevCollector(logger *slog.Logger) (Collector, error) {
	if *oldNetdevDeviceInclude != "" {
		if *netdevDeviceInclude == "" {
			logger.Warn("--collector.netdev.device-whitelist is DEPRECATED and will be removed in 2.0.0, use --collector.netdev.device-include")
			*netdevDeviceInclude = *oldNetdevDeviceInclude
		} else {
			return nil, errors.New("--collector.netdev.device-whitelist and --collector.netdev.device-include are mutually exclusive")
		}
	}

	if *oldNetdevDeviceExclude != "" {
		if *netdevDeviceExclude == "" {
			logger.Warn("--collector.netdev.device-blacklist is DEPRECATED and will be removed in 2.0.0, use --collector.netdev.device-exclude")
			*netdevDeviceExclude = *oldNetdevDeviceExclude
		} else {
			return nil, errors.New("--collector.netdev.device-blacklist and --collector.netdev.device-exclude are mutually exclusive")
		}
	}

	if *netdevDeviceExclude != "" && *netdevDeviceInclude != "" {
		return nil, errors.New("device-exclude & device-include are mutually exclusive")
	}

	if *netdevDeviceExclude != "" {
		logger.Info("Parsed flag --collector.netdev.device-exclude", "flag", *netdevDeviceExclude)
	}

	if *netdevDeviceInclude != "" {
		logger.Info("Parsed Flag --collector.netdev.device-include", "flag", *netdevDeviceInclude)
	}

	return &netDevCollector{
		subsystem:    "network",
		deviceFilter: newDeviceFilter(*netdevDeviceExclude, *netdevDeviceInclude),

View on GitHub (pinned to 17ddd77c59)