--collector.systemd.unit-whitelist and…

Error message

--collector.systemd.unit-whitelist and --collector.systemd.unit-include are mutually exclusive

What it means

NewSystemdCollector rejects combining the deprecated --collector.systemd.unit-whitelist with the new --collector.systemd.unit-include. Both write the same include value, so specifying both explicitly is treated as a configuration conflict.

Solutions

Delete --collector.systemd.unit-whitelist and use --collector.systemd.unit-include only.
Temporarily keep whitelist alone (deprecated path logs a warning and maps it to include).
Search deployment configs (units, containers, ansible) for both spellings and consolidate.

Example fix

// before
--collector.systemd.unit-whitelist='^(ssh|nginx)' --collector.systemd.unit-include='^(sshd)' 
// after
--collector.systemd.unit-include='^(ssh|nginx|sshd)'

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Standardize on unit-include/unit-exclude across all hosts.
Search IaC repos for 'unit-whitelist' and replace.
Centralize exporter flag definitions in one template.

When it happens

Trigger: Setting --collector.systemd.unit-whitelist non-empty while --collector.systemd.unit-include was also explicitly set (systemdUnitIncludeSet is true) when constructing the systemd collector.

Common situations: Post-upgrade configs where old whitelist flags remain and new include flags were added by tooling; copy-pasted example command lines mixing old and new syntax.

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

Appendix: source

Thrown at collector/systemd_linux.go:152

		"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,
		unitTasksCurrentDesc:          unitTasksCurrentDesc,
		unitTasksMaxDesc:              unitTasksMaxDesc,
		systemRunningDesc:             systemRunningDesc,
		summaryDesc:                   summaryDesc,
		nRestartsDesc:                 nRestartsDesc,
		timerLastTriggerDesc:          timerLastTriggerDesc,
		socketAcceptedConnectionsDesc: socketAcceptedConnectionsDesc,
		socketCurrentConnectionsDesc:  socketCurrentConnectionsDesc,

View on GitHub (pinned to 17ddd77c59)