What causes "invalid NTP port number %d; must be between 1 and 65535 inclusive" in prometheus/node_exporter?

Use the standard NTP port: --collector.ntp.server-port=123.

invalid NTP port number

Error message

invalid NTP port number %d; must be between 1 and 65535 inclusive

What it means

NewNtpCollector validates --collector.ntp.server-port and accepts only values from 1 to 65535 inclusive. Ports outside this range cannot be valid UDP ports, so the constructor returns this formatted error at startup.

Solutions

Use the standard NTP port: --collector.ntp.server-port=123.
If a custom local server runs on another port, pick an integer in [1,65535].
Correct any template/default that renders 0 or >65535 for this flag.
Note the collector also logs a deprecation warning; consider migrating to an alternative NTP exporter.

Example fix

// before
//   --collector.ntp.server-port=0
// after
//   --collector.ntp.server-port=123

Defensive patterns

Strategy: validation

Validate before calling

# shell: validate UDP port range before launch
[ "$NTP_PORT" -ge 1 ] && [ "$NTP_PORT" -le 65535 ] || { echo "invalid --collector.ntp.server-port: $NTP_PORT"; exit 1; }

Prevention

Use port 123 (standard NTP) unless the local server deliberately listens elsewhere.
Never use 0 intending 'default'; it is rejected.
Validate port fields in config templates against 1-65535.
Watch for deprecation warnings and plan migration away from this collector.

When it happens

Trigger: Starting node_exporter with --collector.ntp.server-port=0, a negative number, or a value above 65535 (e.g. 65536); the int flag parses successfully but fails semantic validation here.

Common situations: Setting port 0 intending 'default NTP port' (use 123 instead); mixing up decimal/hex or appending stray digits; config templating that substitutes an empty or invalid default that becomes 0.

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

Appendix: source

Thrown at collector/ntp.go:78

// 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(
			prometheus.BuildFQName(namespace, ntpSubsystem, "leap"),
			"NTPD leap second indicator, 2 bits.",
			nil, nil,
		), prometheus.GaugeValue},
		rtt: typedDesc{prometheus.NewDesc(
			prometheus.BuildFQName(namespace, ntpSubsystem, "rtt_seconds"),
			"RTT to NTPD.",
			nil, nil,

View on GitHub (pinned to 17ddd77c59)