nats-io/nats-server · error

beginning of range (%d) beyond end of range (%d): %s

Error message

beginning of range (%d) beyond end of range (%d): %s

What it means

Cron expression range parser: within a single range component the start value is greater than the end value (e.g. 50-10), making the range unsatisfiable.

Source

Thrown at server/cron.go:228

		// Special handling: "N/step" means "N-max/step".
		if singleDigit {
			end = r.max
		}
		if step > 1 {
			extra = 0
		}
	default:
		return 0, fmt.Errorf("too many slashes: %s", expr)
	}

	if start < r.min {
		return 0, fmt.Errorf("beginning of range (%d) below minimum (%d): %s", start, r.min, expr)
	}
	if end > r.max {
		return 0, fmt.Errorf("end of range (%d) above maximum (%d): %s", end, r.max, expr)
	}
	if start > end {
		return 0, fmt.Errorf("beginning of range (%d) beyond end of range (%d): %s", start, end, expr)
	}
	if step == 0 {
		return 0, fmt.Errorf("step of range should be a positive number: %s", expr)
	}
	return getBits(start, end, step) | extra, nil
}

// parseIntOrName returns the (possibly-named) integer contained in expr.
func parseIntOrName(expr string, names map[string]uint) (uint, error) {
	if names != nil {
		if namedInt, ok := names[strings.ToLower(expr)]; ok {
			return namedInt, nil
		}
	}
	return mustParseInt(expr)
}

// mustParseInt parses the given expression as an int or returns an error.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Split wrap-around ranges into two comma-separated ascending ranges: "22-23,0-2"
2. Swap the endpoints so start <= end
3. Use '*' with steps if a recurring spread is intended

Example fix

// before (hour field)
 expr := "22-2"
// after
 expr := "22-23,0-2"

if start > end {
    return fmt.Errorf("range %d-%d is inverted; split wrap-around into comma ranges", start, end)
}

When it happens

Trigger: Any '-' range where the left value is greater than the right, e.g. hours "22-2", minutes "50-10", parsed via parseCron -> getField -> getRange.

Common situations: Trying to express a wrap-around overnight window (22:00-02:00) in one range; typos transposing range endpoints.

Related errors

• beginning of range (%d) below minimum (%d): %s
• end of range (%d) above maximum (%d): %s
• step of range should be a positive number: %s
• pattern requires 6 fields, got %d
• too many hyphens: %s

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