{"record":{"id":"d7d7ee20f8e50d8c","repo":"prometheus/node_exporter","slug":"collector-netdev-device-blacklist-and-collecto","errorCode":null,"errorMessage":"--collector.netdev.device-blacklist and --collector.netdev.device-exclude are mutually exclusive","messagePattern":"--collector\\.netdev\\.device-blacklist and --collector\\.netdev\\.device-exclude are mutually exclusive","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/netdev_common.go","lineNumber":69,"sourceCode":"}\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)\n\t}\n\n\tif *netdevDeviceInclude != \"\" {\n\t\tlogger.Info(\"Parsed Flag --collector.netdev.device-include\", \"flag\", *netdevDeviceInclude)\n\t}\n\n\treturn &netDevCollector{\n\t\tsubsystem:    \"network\",\n\t\tdeviceFilter: newDeviceFilter(*netdevDeviceExclude, *netdevDeviceInclude),","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/prometheus/node_exporter/blob/17ddd77c59ba27e1508e9f7894b1e55b44d6aed3/collector/netdev_common.go#L51-L87","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","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."],"exampleFix":"// before\nnode_exporter --collector.netdev.device-blacklist=veth.* --collector.netdev.device-exclude=lo\n// after\nnode_exporter --collector.netdev.device-exclude=lo","handlingStrategy":"validation","validationCode":"# Fail the deploy script if both exclude flags are present\nif [[ -n \"$BLACKLIST\" && -n \"$EXCLUDE\" ]]; then\n  echo \"ERROR: device-blacklist and device-exclude 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 exclude-flag conflict; remove deprecated device-blacklist\", \"err\", err)\n    os.Exit(2)\n}","preventionTips":["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."],"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"}