nats-io/nats-server · error

integer '%s' is out of the range

Error message

integer '%s' is out of the range

What it means

When a config value looks like a number with a size suffix (e.g. 2GB, 1024KB), processItem parses the digit part with strconv.ParseInt on 64 bits. If parsing fails specifically with ErrRange, the value overflows int64 and the parser reports "integer '<value>' is out of the range".

Source

Thrown at conf/parse.go:314

	case itemMapEnd:
		setValue(it, p.popContext())
	case itemString:
		// FIXME(dlc) sanitize string?
		setValue(it, it.val)
	case itemInteger:
		lastDigit := 0
		for _, r := range it.val {
			if !unicode.IsDigit(r) && r != '-' {
				break
			}
			lastDigit++
		}
		numStr := it.val[:lastDigit]
		num, err := strconv.ParseInt(numStr, 10, 64)
		if err != nil {
			if e, ok := err.(*strconv.NumError); ok &&
				e.Err == strconv.ErrRange {
				return fmt.Errorf("integer '%s' is out of the range", it.val)
			}
			return fmt.Errorf("expected integer, but got '%s'", it.val)
		}
		// Process a suffix
		suffix := strings.ToLower(strings.TrimSpace(it.val[lastDigit:]))

		switch suffix {
		case "":
			setValue(it, num)
		case "k":
			setValue(it, num*1000)
		case "kb", "ki", "kib":
			setValue(it, num*1024)
		case "m":
			setValue(it, num*1000*1000)
		case "mb", "mi", "mib":
			setValue(it, num*1024*1024)
		case "g":

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Reduce the literal to a value within int64 (max 9223372036854775807)
2. Use suffixes (KB/MB/GB) instead of enormous raw numbers
3. Check for accidentally duplicated digits in generated configs
4. Validate the config with `nats-server -t` before deployment

Example fix

// before
max_payload: 99999999999999999999
// after
max_payload: 1GB

func checkInt64(v string) error {
    if _, err := strconv.ParseInt(strings.TrimRight(v, "KMGTPBkmgtpb"), 10, 64); err != nil {
        if errors.Is(err, strconv.ErrRange) {
            return fmt.Errorf("%s exceeds int64 range", v)
        }
    }
    return nil
}

When it happens

Trigger: Any numeric config value whose integer magnitude exceeds int64 range even before suffix application — e.g. `max_payload: 99999999999999999999`, or durations/sizes with absurdly large digit strings in conf values parsed by processItem's numeric branch.

Common situations: Fat-fingered extra digits; generation of configs from scripts concatenating numbers; unit confusion leading to giant numbers like 9999PB written as raw digit strings.

Related errors

• config is invalid (%s:%d:%d)
• expected integer, but got '%s'
• unable to plug TLS verify connection, config is nil
• OCSP peer verification for client connections requires TLS v
• unable to register client OCSP verification

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/d88c6ef08706ae3d. Report an issue: GitHub.