temporalio/temporal · error

out of range

Error message

out of range

What it means

errOutOfRange is returned by calendar spec parsing helpers (parseValue/makeRange) when a numeric or named component of a Schedule calendar spec or cron string falls outside the field's allowed bounds — e.g. minute 61, month 13, day-of-month 32, or a year outside minCalendarYear..maxCalendarYear. It is aggregated by parseCalendarToStructured into a combined error listing every invalid field.

Source

Thrown at service/worker/scheduler/calendar.go:53

	maxCalendarYear = 2100

	// max length of one calendar comment field
	maxCommentLen = 200
)

const (
	// Modes for parsing range strings: all modes accept decimal integers
	parseModeInt parseMode = iota
	// parseModeYear is like parseModeInt but returns an empty range for the default
	parseModeYear
	// parseModeMonth also accepts month name prefixes (at least three letters)
	parseModeMonth
	// parseModeDow also accepts day-of-week prefixes (at least two letters)
	parseModeDow
)

var (
	errOutOfRange               = errors.New("out of range")
	errConflictingTimezoneNames = errors.New("conflicting timezone names")

	monthStrings = []string{
		"january",
		"february",
		"march",
		"april",
		"may",
		"june",
		"july",
		"august",
		"september",
		"october",
		"november",
		"december",
	}

	dowStrings = []string{

View on GitHub (pinned to bde624efd1)

Solutions

1. Read the field names in the joined error message and clamp each component to its valid range (Second 0-59, Minute 0-59, Hour 0-23, DayOfMonth 1-31, Month 1-12, DayOfWeek 0-7).
2. Validate the cron/calendar string with a standard cron parser or the Temporal CLI before applying it to the schedule.
3. Prefer month/day names or the structured CalendarSpec API over raw integers to avoid off-by-one errors.
4. Check the Year field is within minCalendarYear..maxCalendarYear if a year is specified.

Example fix

// before
spec := &schedulepb.CalendarSpec{Minute: "61", Hour: "9"} // minute out of range
// after
spec := &schedulepb.CalendarSpec{Minute: "0", Hour: "9"}

func checkRange(field string, v, min, max int) error {
	if v < min || v > max {
		return fmt.Errorf("%s %d out of range [%d,%d]", field, v, min, max)
	}
	return nil
}

spec, err := schedule.NewCalendarSpec(...) // or update via CLI
if err != nil && strings.Contains(err.Error(), "out of range") {
	// clamp fields and resubmit
}

When it happens

Trigger: Creating/updating a Temporal Schedule (or starting a scheduler workflow) whose CalendarSpec or cron string contains a value exceeding the field's range: Second>59, Minute>59, Hour>23, DayOfMonth>31, Month>12, DayOfWeek>7, or Year outside the supported window.

Common situations: Hand-writing cron/calendar expressions and transposing digits; using 1-based day-of-week in a field expecting 0-based (0-7); scripts generating specs with off-by-one bounds; localizing month names that the parser doesn't recognize and mis-sizes.

Related errors

• ${errs}
• invalid calendar spec: ${errs}
• conflicting timezone names
• CronString has time zone but missing fields
• CronString does not have 5-7 fields

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/82c9c7378d1bbbbd. Report an issue: GitHub.