pocketbase/pocketbase · error

invalid segment step - step > 1 could be used only with the

Error message

invalid segment step - step > 1 could be used only with the wildcard or range format

What it means

Returned by parseCronSegment when a step value greater than 1 is combined with a single bare value instead of a wildcard or range — e.g. the minutes segment "5/2". The parser only supports steps on "*" (*/2) or on ranges (10-50/2); a step on a single number has no meaning (it fires at most once), so it is rejected.

Source

Thrown at tools/cron/schedule.go:177

				return nil, fmt.Errorf("invalid segment step boundary - the step must be between 1 and the %d", max)
			}
			step = parsedStep
		default:
			return nil, errors.New("invalid segment step format - must be in the format */n or 1-30/n")
		}

		// find the min and max range of the segment part
		var rangeMin, rangeMax int
		if stepParts[0] == "*" {
			rangeMin = min
			rangeMax = max
		} else {
			// single digit (1) or range (1-30)
			rangeParts := strings.Split(stepParts[0], "-")
			switch len(rangeParts) {
			case 1:
				if step != 1 {
					return nil, errors.New("invalid segment step - step > 1 could be used only with the wildcard or range format")
				}
				parsed, err := strconv.Atoi(rangeParts[0])
				if err != nil {
					return nil, err
				}
				if parsed < min || parsed > max {
					return nil, errors.New("invalid segment value - must be between the min and max of the segment")
				}
				rangeMin = parsed
				rangeMax = rangeMin
			case 2:
				parsedMin, err := strconv.Atoi(rangeParts[0])
				if err != nil {
					return nil, err
				}
				if parsedMin < min || parsedMin > max {
					return nil, fmt.Errorf("invalid segment range minimum - must be between %d and %d", min, max)
				}

View on GitHub (pinned to 5d217ddb50)

Solutions

1. Rewrite the single-value step as an explicit range with the desired start: "5-59/2" for minutes.
2. If you meant 'every N', use the wildcard form "*/2".
3. If you meant the single value, drop the step: just "5".
4. Test the expression against NewSchedule in a unit test when it comes from user/config input.

Example fix

# before
0 5/2 * * *   # step on single value -> error

# after
0 5-59/2 * * *  # every 2 minutes starting at :05

// reject value/step on a bare number before calling Add
var bareStepRe = regexp.MustCompile(`^\d+/\d+$`)
if bareStepRe.MatchString(segment) {
    return fmt.Errorf("%q: use */N or min-max/N instead of value/N", segment)
}

if _, err := cron.NewSchedule(expr); err != nil {
    return fmt.Errorf("schedule %q rejected: %w — rewrite single-value steps as ranges", expr, err)
}

When it happens

Trigger: Writing a segment like "5/2", "12/5" or "1/10" in any of the five fields; porting expressions from systems (e.g. some cloud schedulers) that accept value/step syntax.

Common situations: Developer intends 'every 2 starting at 5' and writes 5/2 instead of the range form; converting cron from Kubernetes/AWS EventBridge notation which has slightly different step semantics.

Related errors

• invalid cron expression - must be a valid macro or to have e
• invalid segment value - must be between the min and max of t
• invalid segment range format - the range must have 1 or 2 pa
• failed to add new cron job: fn must be non-nil function
• invalid_json

AI-assisted analysis of pocketbase/pocketbase@5d217ddb50 (2026-08-15). Data as JSON: /api/errors/c222bbd8acac5602. Report an issue: GitHub.