prometheus/node_exporter · error

invalid NTP protocol version

Error message

invalid NTP protocol version %d; must be 2, 3, or 4

What it means

NewNtpCollector validates --collector.ntp.protocol-version after checking the server flag. The NTP query implementation used by this collector only supports protocol versions 2, 3, and 4; values below 2 or above 4 cause the constructor to return this formatted error at startup.

Solutions

  1. Set --collector.ntp.protocol-version=4 (the most widely supported modern choice).
  2. Use 3 or 2 only if your local server is very old and rejects v4.
  3. Check the current flag value in your service/unit file and correct it to an integer in [2,4].
  4. Remember this collector is deprecated; if you need newer protocol behavior, use an alternative NTP exporter.

Example fix

// before
//   --collector.ntp.protocol-version=5
// after
//   --collector.ntp.protocol-version=4
Defensive patterns

Strategy: validation

Validate before calling

# shell: reject protocol versions outside 2-4 before launch
case "$NTP_PROTO" in 2|3|4) ;; *) echo "invalid --collector.ntp.protocol-version: $NTP_PROTO"; exit 1;; esac

Prevention

When it happens

Trigger: Starting node_exporter with --collector.ntp.protocol-version=1, 0, 5, 6, 7, or any integer outside [2,4] passed via the flag (the value is an int flag, so non-numeric values fail earlier at flag parsing).

Common situations: Users assuming NTPv5 or draft versions are supported on newer systems; copying old ntpdate-era defaults like version 1; setting version 4 explicitly is fine, but 5 is not despite newer NTP drafts existing.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at collector/ntp.go:70

	logger                                                                 *slog.Logger
}

func init() {
	registerCollector("ntp", defaultDisabled, NewNtpCollector)
}

// NewNtpCollector returns a new Collector exposing sanity of local NTP server.
// Default definition of "local" is:
// - collector.ntp.server address is a loopback address (or collector.ntp.server-is-mine flag is turned on)
// - the server is reachable with outgoing IP_TTL = 1
func NewNtpCollector(logger *slog.Logger) (Collector, error) {
	ipaddr := net.ParseIP(*ntpServer)
	if !*ntpServerIsLocal && (ipaddr == nil || !ipaddr.IsLoopback()) {
		return nil, fmt.Errorf("only IP address of local NTP server is valid for --collector.ntp.server")
	}

	if *ntpProtocolVersion < 2 || *ntpProtocolVersion > 4 {
		return nil, fmt.Errorf("invalid NTP protocol version %d; must be 2, 3, or 4", *ntpProtocolVersion)
	}

	if *ntpOffsetTolerance < 0 {
		return nil, fmt.Errorf("offset tolerance must be non-negative")
	}

	if *ntpServerPort < 1 || *ntpServerPort > 65535 {
		return nil, fmt.Errorf("invalid NTP port number %d; must be between 1 and 65535 inclusive", *ntpServerPort)
	}

	logger.Warn("This collector is deprecated and will be removed in the next major version release.")
	return &ntpCollector{
		stratum: typedDesc{prometheus.NewDesc(
			prometheus.BuildFQName(namespace, ntpSubsystem, "stratum"),
			"NTPD stratum.",
			nil, nil,
		), prometheus.GaugeValue},
		leap: typedDesc{prometheus.NewDesc(

View on GitHub (pinned to 17ddd77c59)