What causes "invalid flag value %q" in prometheus/node_exporter?

Fix the --collector.perf.cpus value so every range is in the form START-END or START-END:STRIDE, e.g. "0-3,8-11:2".

invalid flag value

Error message

invalid flag value %q

What it means

perfCPUFlagToCPUs parses the --collector.perf.cpus flag, which accepts comma-separated CPU numbers, ranges (0-3), and strides (1-10:5). This error is thrown when a range element like "0-3" splits on "-" into something other than exactly two parts (e.g. "0-" , "-3", or a nested range like "0-3-6"). The library rejects the whole flag value rather than guessing the intended CPU set.

Solutions

Fix the --collector.perf.cpus value so every range is in the form START-END or START-END:STRIDE, e.g. "0-3,8-11:2".
If you want individual CPUs, list them without dashes: "0,1,2".
Validate the flag with a quick check that each dash-containing element has exactly one dash before the optional ":stride" part.

Example fix

// before
node_exporter --collector.perf.cpus="0-3-8"
// after
node_exporter --collector.perf.cpus="0-3,8"

Defensive patterns

Strategy: validation

Validate before calling

package main

import (
	"fmt"
	"regexp"
)

var cpuFlagRe = regexp.MustCompile(`^\d+(-\d+(:\d+)?)?(,\d+(-\d+(:\d+)?)?)*$`)

func validPerfCPUFlag(v string) error {
	if !cpuFlagRe.MatchString(v) {
		return fmt.Errorf("invalid --collector.perf.cpus %q: ranges must be START-END[:STRIDE]", v)
	}
	return nil
}

Prevention

Validate the flag format before launching node_exporter in deployment scripts.
Use only canonical forms: single CPUs, START-END, or START-END:STRIDE separated by commas.
Avoid hand-editing generated flag strings; generate them programmatically and test with a dry run.

When it happens

Trigger: Called from NewPerfCollector when --collector.perf.cpus contains a subset containing "-" whose first colon-stripped part does not split into exactly two dash-separated fields; e.g. "0-", "-2", "0-3-6", or trailing commas producing empty ranges.

Common situations: Typos in the flag value on the node_exporter command line, copy-pasting a CPU list from cpuset syntax (e.g. "0-3,8-11" written as "0-3-8-11"), or generating the flag from a script that emits empty range halves.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

AI-assisted analysis of prometheus/node_exporter@17ddd77c59 (2026-09-07). Data as JSON: /api/errors/7917a643139474f5. Report an issue: GitHub.

Appendix: source

Thrown at collector/perf_linux.go:143

				return nil, err
			}
			cpus = append(cpus, cpu)
			continue
		}

		stride := 1
		// Handle strides, ie 1-10:5 should yield 1,5,10
		strideSet := strings.Split(subset, ":")
		if len(strideSet) == 2 {
			stride, err = strconv.Atoi(strideSet[1])
			if err != nil {
				return nil, err
			}
		}

		rangeSet := strings.Split(strideSet[0], "-")
		if len(rangeSet) != 2 {
			return nil, fmt.Errorf("invalid flag value %q", cpuFlag)
		}
		start, err := strconv.Atoi(rangeSet[0])
		if err != nil {
			return nil, err
		}
		end, err := strconv.Atoi(rangeSet[1])
		if err != nil {
			return nil, err
		}
		for i := start; i <= end; i += stride {
			cpus = append(cpus, i)
		}
	}

	return cpus, nil
}

// perfTracepoint is a struct for holding tracepoint information.

View on GitHub (pinned to 17ddd77c59)