--collector.diskstats.ignored-devices and…

Error message

--collector.diskstats.ignored-devices and --collector.diskstats.device-exclude are mutually exclusive

What it means

In newDiskstatsDeviceFilter (diskstats_common.go), node_exporter refuses to start when both the deprecated --collector.diskstats.ignored-devices and the replacement --collector.diskstats.device-exclude are set, because it cannot tell which the operator intended. This is a startup-time configuration validation error raised by NewDiskstatsCollector.

Solutions

Remove --collector.diskstats.ignored-devices and keep only --collector.diskstats.device-exclude with the same regex value
If you truly want the old flag temporarily, unset --collector.diskstats.device-exclude entirely (presence of the flag counts, even with empty value semantics differ)
Search your unit file/container args/config management for both flags and keep exactly one

Example fix

// before
node_exporter --collector.diskstats.ignored-devices='^(ram|loop)\d+$' --collector.diskstats.device-exclude='^(zram)\d+$'
// after
node_exporter --collector.diskstats.device-exclude='^(ram|loop|zram)\d+$'

Defensive patterns

Strategy: validation

Validate before calling

# shell pre-flight before launching: only one of the two flags may be set
args=$(tr '\0' '\n' </proc/1/cmdline 2>/dev/null || true)
if echo "$args" | grep -q 'ignored-devices=' && echo "$args" | grep -q 'diskstats.device-exclude='; then
  echo "conflict: drop --collector.diskstats.ignored-devices and use --collector.diskstats.device-exclude only"
fi

Prevention

Standardize on --collector.diskstats.device-exclude; treat ignored-devices as removed
Add config-management assertions that only one flag is ever rendered
Grep service unit files/containers for both flags during upgrades
Write a startup smoke test that catches flag conflicts before production

When it happens

Trigger: Both flags --collector.diskstats.ignored-devices (old, deprecated) and --collector.diskstats.device-exclude (new) are given non-empty values on the command line (oldDiskstatsDeviceExclude != "" AND diskstatsDeviceExcludeSet).

Common situations: Upgrading node_exporter and merging old service unit files with new documentation examples, leaving both flags in place; config-management tools (Puppet/Ansible) adding the new flag without removing the deprecated one.

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/f404407c28cd9bd9. Report an issue: GitHub.

Appendix: source

Thrown at collector/diskstats_common.go:99

		diskLabelNames,
		nil,
	)

	writeTimeSecondsDesc = prometheus.NewDesc(
		prometheus.BuildFQName(namespace, diskSubsystem, "write_time_seconds_total"),
		"This is the total number of seconds spent by all writes.",
		diskLabelNames,
		nil,
	)
)

func newDiskstatsDeviceFilter(logger *slog.Logger) (deviceFilter, error) {
	if *oldDiskstatsDeviceExclude != "" {
		if !diskstatsDeviceExcludeSet {
			logger.Warn("--collector.diskstats.ignored-devices is DEPRECATED and will be removed in 2.0.0, use --collector.diskstats.device-exclude")
			*diskstatsDeviceExclude = *oldDiskstatsDeviceExclude
		} else {
			return deviceFilter{}, errors.New("--collector.diskstats.ignored-devices and --collector.diskstats.device-exclude are mutually exclusive")
		}
	}
	if *diskstatsDeviceInclude != "" {
		if diskstatsDeviceExcludeSet && *diskstatsDeviceExclude != "" {
			return deviceFilter{}, errors.New("device-exclude & device-include are mutually exclusive")
		}
		*diskstatsDeviceExclude = ""
	}

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

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

	return newDeviceFilter(*diskstatsDeviceExclude, *diskstatsDeviceInclude), nil

View on GitHub (pinned to 17ddd77c59)