agent ' ' `start_calendar_interval. ` must be between and

Error message

agent '{agent_name}' `start_calendar_interval.{field}` must be between {min} and {max}

What it means

Thrown by the shared range validator for `StartCalendarInterval` fields when a provided calendar value falls outside its valid range: minute 0-59, hour 0-23, day 1-31, weekday 0-7, month 1-12. These mirror launchd/cron calendar semantics, and out-of-range values would never match a real time. The error names the specific field and its allowed min/max.

Solutions

Clamp the offending field into its documented range (minute 0-59, hour 0-23, day 1-31, weekday 0-7, month 1-12).
Re-check 0-based vs 1-based semantics: weekday starts at 0 (Sunday) and allows 7, but day and month start at 1.
Split values that can't be expressed in one field (e.g. minute 90) into multiple intervals or use `start_interval` instead.
Use a cron/launchd reference table when translating schedules.

Example fix

# before
[agents.report.system.start_calendar_interval]
minute = 90

# after
[agents.report.system.start_calendar_interval]
minute = 30

Defensive patterns

Strategy: validation

Validate before calling

const RANGES = { minute:[0,59], hour:[0,23], day:[1,31], weekday:[0,7], month:[1,12] };
for (const [f,[min,max]] of Object.entries(RANGES)) {
  const v = interval[f];
  if (v !== undefined && (v < min || v > max)) throw new Error(`${f} must be ${min}..${max}`);
}

Type guard

function inRange(v, min, max) { return v !== undefined && v >= min && v <= max; }

Prevention

Keep a reference table: minute 0-59, hour 0-23, day 1-31, weekday 0-7, month 1-12.
Remember weekday is 0-based (0 and 7 = Sunday); day and month are 1-based.
Unit-test schedule generators against the ranges.

When it happens

Trigger: Setting `minute = 60`, `hour = 24`, `month = 0`, `day = 32`, or `weekday = 8` in a `start_calendar_interval` entry; off-by-one mistakes like `month = 13` or 1-based/0-based confusion on weekday (0 and 7 are both Sunday, but 8 is invalid).

Common situations: Porting cron expressions where minute ranges differ; confusing day-of-month ranges (1-31) with hour ranges; forgetting weekday accepts 0-7 while month is 1-12.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/7549826ffb3c58c1. Report an issue: GitHub.

Appendix: source

Thrown at src/system/launchd.rs:212

                    interval.validate(agent_name)?;
                }
                Ok(())
            }
        }
    }
}

fn validate_range(
    agent_name: &str,
    field: &str,
    value: Option<u8>,
    min: u8,
    max: u8,
) -> Result<()> {
    if let Some(value) = value
        && !(min..=max).contains(&value)
    {
        bail!(
            "agent '{agent_name}' `start_calendar_interval.{field}` must be between {min} and {max}"
        );
    }
    Ok(())
}

impl std::fmt::Display for LaunchdRequest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} ({})", self.name, self.label)
    }
}

pub(crate) fn is_available() -> bool {
    cfg!(target_os = "macos") && crate::file::which("launchctl").is_some()
}

pub(crate) fn unavailable_reason() -> String {
    if cfg!(target_os = "macos") {

View on GitHub (pinned to 533346cc37)