--collector.systemd.unit-blacklist and…

Error message

--collector.systemd.unit-blacklist and --collector.systemd.unit-exclude are mutually exclusive

What it means

NewSystemdCollector refuses to start when both the deprecated --collector.systemd.unit-blacklist and the new --collector.systemd.unit-exclude are explicitly set. Since the flags set the same underlying exclude value, only one may be given.

Solutions

Remove --collector.systemd.unit-blacklist and keep only --collector.systemd.unit-exclude with the same regex value.
If migration is staged, keep blacklist alone (it is translated with a deprecation warning) until the new flag is adopted.
Audit systemd unit files / service overrides for duplicate legacy+new flag pairs.

Example fix

// before
ExecStart=... --collector.systemd.unit-blacklist='.+\.scope' --collector.systemd.unit-exclude='.+\.device'
// after
ExecStart=... --collector.systemd.unit-exclude='+\.scope|.+\.device'

Defensive patterns

Strategy: validation

Validate before calling

legacy := flags.ContainsKey("collector.systemd.unit-blacklist")
modern := flags.ContainsKey("collector.systemd.unit-exclude")
if legacy && modern {
    return errors.New("systemd: drop unit-blacklist, keep only unit-exclude")
}

Prevention

During migration, move values to the new flag and delete the old one in the same change.
Grep systemd units/ansible/container args for 'unit-blacklist'.
Treat deprecation warnings as migration TODOs.

When it happens

Trigger: Setting --collector.systemd.unit-blacklist to a non-empty value while --collector.systemd.unit-exclude was also explicitly provided (systemdUnitExcludeSet is true).

Common situations: Upgrading node_exporter while keeping old blacklist flags in unit files and adding the new exclude flags; automation tools layering new flags on top of legacy ones.

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

Appendix: source

Thrown at collector/systemd_linux.go:144

	socketCurrentConnectionsDesc := prometheus.NewDesc(
		prometheus.BuildFQName(namespace, subsystem, "socket_current_connections"),
		"Current number of socket connections", []string{"name"}, nil)
	socketRefusedConnectionsDesc := prometheus.NewDesc(
		prometheus.BuildFQName(namespace, subsystem, "socket_refused_connections_total"),
		"Total number of refused socket connections", []string{"name"}, nil)
	systemdVersionDesc := prometheus.NewDesc(
		prometheus.BuildFQName(namespace, subsystem, "version"),
		"Detected systemd version", []string{"version"}, nil)
	virtualizationDesc := prometheus.NewDesc(
		prometheus.BuildFQName(namespace, subsystem, "virtualization_info"),
		"Detected virtualization technology", []string{"virtualization_type"}, nil)

	if *oldSystemdUnitExclude != "" {
		if !systemdUnitExcludeSet {
			logger.Warn("--collector.systemd.unit-blacklist is DEPRECATED and will be removed in 2.0.0, use --collector.systemd.unit-exclude")
			*systemdUnitExclude = *oldSystemdUnitExclude
		} else {
			return nil, errors.New("--collector.systemd.unit-blacklist and --collector.systemd.unit-exclude are mutually exclusive")
		}
	}
	if *oldSystemdUnitInclude != "" {
		if !systemdUnitIncludeSet {
			logger.Warn("--collector.systemd.unit-whitelist is DEPRECATED and will be removed in 2.0.0, use --collector.systemd.unit-include")
			*systemdUnitInclude = *oldSystemdUnitInclude
		} else {
			return nil, errors.New("--collector.systemd.unit-whitelist and --collector.systemd.unit-include are mutually exclusive")
		}
	}
	logger.Info("Parsed flag --collector.systemd.unit-include", "flag", *systemdUnitInclude)
	systemdUnitIncludePattern := regexp.MustCompile(fmt.Sprintf("^(?:%s)$", *systemdUnitInclude))
	logger.Info("Parsed flag --collector.systemd.unit-exclude", "flag", *systemdUnitExclude)
	systemdUnitExcludePattern := regexp.MustCompile(fmt.Sprintf("^(?:%s)$", *systemdUnitExclude))

	return &systemdCollector{
		unitDesc:                      unitDesc,
		unitStartTimeDesc:             unitStartTimeDesc,

View on GitHub (pinned to 17ddd77c59)