What causes "expected integer, but got '%s'" in nats-io/nats-server?

Fix the value at the reported location to be a plain integer (e.g. port: 4222)

expected integer, but got '%s'

Error message

expected integer, but got '%s'

What it means

In processItem's numeric handling, if strconv.ParseInt fails with anything other than ErrRange (i.e. the token is not a valid integer at all), the parser returns "expected integer, but got '%s'". The library throws it when a config option requires a number but receives non-numeric text.

Source

Thrown at conf/parse.go:316

	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":
			setValue(it, num*1000*1000*1000)
		case "gb", "gi", "gib":

View on GitHub (pinned to 3a66a489d2)

Solutions

Fix the value at the reported location to be a plain integer (e.g. port: 4222)
Remove quotes, spaces, underscores or units from numeric-only options
Verify env substitutions ($VAR) expand to valid numbers
Run `nats-server -t -c file.conf` to catch it before startup

Example fix

// before
port: "4222x"
// after
port: 4222

Defensive patterns

Strategy: validation

Validate before calling

func isPlainInteger(s string) bool {
    s = strings.TrimSpace(s)
    if s == "" { return false }
    _, err := strconv.ParseInt(s, 10, 64)
    return err == nil
}
// apply to every numeric option value before parsing

Try / catch

cfg, err := conf.ParseFile(fp)
if err != nil {
    if strings.Contains(err.Error(), "expected integer, but got") {
        log.Fatalf("numeric option has non-numeric value in %s: %v", fp, err)
    }
    return err
}

Prevention

Keep numeric options unquoted and free of units/spaces
Validate env-var substitutions resolve to numbers
Strip invisible characters when copying values between editors
Gate deploys on nats-server -t config validation

When it happens

Trigger: A numeric option given a string or malformed value, e.g. `port: "4222x"`, `max_payload: abc`, or a value containing spaces/underscores like `1 024`; the digit-prefix parse of the token fails with a non-range error.

Common situations: Typo in numeric values; quoting numbers with stray characters; env-var interpolation producing empty or non-numeric text; copy/paste inserting invisible characters into numbers.

Related errors

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