{"record":{"id":"f6d6e441f0ce24db","repo":"prometheus/node_exporter","slug":"collector-netdev-device-whitelist-and-collecto","errorCode":null,"errorMessage":"--collector.netdev.device-whitelist and --collector.netdev.device-include are mutually exclusive","messagePattern":"--collector\\.netdev\\.device-whitelist and --collector\\.netdev\\.device-include are mutually exclusive","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/netdev_common.go","lineNumber":60,"sourceCode":"\tmetricDescsMutex sync.Mutex\n\tmetricDescs      map[string]*prometheus.Desc\n\tlogger           *slog.Logger\n}\n\ntype netDevStats map[string]map[string]uint64\n\nfunc init() {\n\tregisterCollector(\"netdev\", defaultEnabled, NewNetDevCollector)\n}\n\n// NewNetDevCollector returns a new Collector exposing network device stats.\nfunc NewNetDevCollector(logger *slog.Logger) (Collector, error) {\n\tif *oldNetdevDeviceInclude != \"\" {\n\t\tif *netdevDeviceInclude == \"\" {\n\t\t\tlogger.Warn(\"--collector.netdev.device-whitelist is DEPRECATED and will be removed in 2.0.0, use --collector.netdev.device-include\")\n\t\t\t*netdevDeviceInclude = *oldNetdevDeviceInclude\n\t\t} else {\n\t\t\treturn nil, errors.New(\"--collector.netdev.device-whitelist and --collector.netdev.device-include are mutually exclusive\")\n\t\t}\n\t}\n\n\tif *oldNetdevDeviceExclude != \"\" {\n\t\tif *netdevDeviceExclude == \"\" {\n\t\t\tlogger.Warn(\"--collector.netdev.device-blacklist is DEPRECATED and will be removed in 2.0.0, use --collector.netdev.device-exclude\")\n\t\t\t*netdevDeviceExclude = *oldNetdevDeviceExclude\n\t\t} else {\n\t\t\treturn nil, errors.New(\"--collector.netdev.device-blacklist and --collector.netdev.device-exclude are mutually exclusive\")\n\t\t}\n\t}\n\n\tif *netdevDeviceExclude != \"\" && *netdevDeviceInclude != \"\" {\n\t\treturn nil, errors.New(\"device-exclude & device-include are mutually exclusive\")\n\t}\n\n\tif *netdevDeviceExclude != \"\" {\n\t\tlogger.Info(\"Parsed flag --collector.netdev.device-exclude\", \"flag\", *netdevDeviceExclude)","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/prometheus/node_exporter/blob/17ddd77c59ba27e1508e9f7894b1e55b44d6aed3/collector/netdev_common.go#L42-L78","documentation":"The netdev collector accepts device filters via new flags (--collector.netdev.device-include) and deprecated aliases (--collector.netdev.device-whitelist). If both the old and new include flags are set to non-empty values, the collector refuses to guess which to use and returns this mutually-exclusive error at construction time (NewNetDevCollector), so the netdev collector never starts.","triggerScenarios":"Starting node_exporter with BOTH --collector.netdev.device-whitelist and --collector.netdev.device-include set to non-empty values, e.g. `--collector.netdev.device-whitelist=eth0 --collector.netdev.device-include=eth1`. If only the old flag is set, it is silently migrated with a deprecation warning instead.","commonSituations":"Flag migration: operators update configs/scripts to the new flag but an old systemd unit, chef/puppet manifest, or dropped-in args file still passes the deprecated whitelist flag; layered configuration (base image flags + override file) accumulating both flags.","solutions":["Remove the deprecated --collector.netdev.device-whitelist flag and keep only --collector.netdev.device-include.","Search all launch points (systemd units, Docker CMD/args, k8s manifests, config management) for the old flag and delete it.","If you must keep old flags during a rollout, set only the old flag — it is migrated automatically with a warning — but plan removal before 2.0.0.","Restart node_exporter after cleaning the flags; the collector will start normally."],"exampleFix":"// before\nnode_exporter --collector.netdev.device-whitelist=eth0 --collector.netdev.device-include=eth1\n// after\nnode_exporter --collector.netdev.device-include=eth1","handlingStrategy":"validation","validationCode":"# Before launching node_exporter, assert the flag pair is not duplicated\nif [[ -n \"$WHITELIST\" && -n \"$INCLUDE\" ]]; then\n  echo \"ERROR: device-whitelist and device-include are mutually exclusive\" >&2\n  exit 1\nfi","typeGuard":null,"tryCatchPattern":"c, err := NewNetDevCollector(logger)\nif err != nil && strings.Contains(err.Error(), \"mutually exclusive\") {\n    logger.Error(\"netdev flag conflict in launch configuration\", \"err\", err)\n    os.Exit(2) // fail fast at startup; configuration error, not transient\n}","preventionTips":["Standardize on the new flags (device-include/device-exclude) and delete deprecated ones repo-wide.","Add a startup smoke test that runs node_exporter --collector.disable-defaults --collector.netdev to catch flag conflicts in CI.","Audit systemd drop-ins and container arg layers that can accumulate duplicate flags.","Read startup logs for the DEPRECATED warning — it signals a flag that will hard-fail if paired later."],"tags":["cli","configuration","netdev","deprecated-flags"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"17ddd77c59ba27e1508e9f7894b1e55b44d6aed3","analyzedAt":"2026-09-07T17:54:06.211Z","contentChangedAt":"2026-09-07T17:54:06.211Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}