What causes "agent '{name}' `nice` must be between -20 and 20" in jdx/mise?

Set nice to a value within -20..=20 (clamp, e.g. 25 -> 20, -21 -> -20)

agent '{name}' `nice` must be between -20 and 20

Error message

agent '{name}' `nice` must be between -20 and 20

What it means

The `nice` value maps to the launchd plist Nice key, which the kernel constrains to the range -20 (highest priority) through 20 (lowest). from_toml validates any provided nice value against this inclusive range and rejects values outside it. This prevents writing a plist launchd or the kernel would refuse.

Source

Thrown at src/system/launchd.rs:124

    pub state: LaunchdState,
}

impl LaunchdRequest {
    pub(crate) fn from_toml(name: String, config: LaunchdTomlConfig) -> Result<Self> {
        if !valid_name(&name) {
            bail!("agent name '{name}' must contain only letters, numbers, '.', '_', or '-'");
        }
        let Some(program) = config.program.map(|s| s.trim().to_string()) else {
            bail!("agent '{name}' must set `program`");
        };
        if program.is_empty() {
            bail!("agent '{name}' must set a non-empty `program`");
        }
        if config.keep_alive && config.keep_alive_on_failure {
            bail!("agent '{name}' cannot set both `keep_alive` and `keep_alive_on_failure`");
        }
        if config.nice.is_some_and(|nice| !(-20..=20).contains(&nice)) {
            bail!("agent '{name}' `nice` must be between -20 and 20");
        }
        if let Some(interval) = &config.start_calendar_interval {
            interval.validate(&name)?;
        }
        for dir in &config.queue_directories {
            if dir.trim().is_empty() {
                bail!("agent '{name}' `queue_directories` must not contain empty entries");
            }
            // checked against the raw string rather than `Path::is_absolute` on the
            // expanded value: the plist is consumed by macOS launchd, so POSIX rules
            // apply regardless of the platform parsing the config, and on Windows
            // `Path::new("/var/spool").is_absolute()` is false (root, but no prefix)
            if !is_absolute_launchd_path(dir) {
                bail!(
                    "agent '{name}' `queue_directories` entry '{dir}' must be an absolute path \
                     (launchd requires absolute paths; `~` and `~/` are expanded)"
                );
            }

View on GitHub (pinned to afd2eddd3a)

Solutions

Set nice to a value within -20..=20 (clamp, e.g. 25 -> 20, -21 -> -20)
Remove the `nice` key if custom priority is not needed
Double-check the intended priority and use 0 (default) or small negative values only if you have permission to raise priority

Example fix

// before
[launchd.my-agent]
nice = 25
// after
[launchd.my-agent]
nice = 20

Defensive patterns

Strategy: validation

Validate before calling

if let Some(nice) = cfg.get("nice").and_then(|v| v.as_integer()) {
    if !(-20..=20).contains(&nice) {
        anyhow::bail!("nice must be between -20 and 20, got {nice}");
    }
}

Prevention

Remember nice is -20..=20, matching the kernel's range
Clamp user-supplied priority values before writing config
Omit `nice` unless priority tuning is actually required

When it happens

Trigger: Setting nice to an integer outside -20..=20 in a [launchd.<name>] section, e.g. nice = 25 or nice = -21.

Common situations: Confusing nice with other priority scales (e.g. -100..100); typos like an extra digit; copying an rlimit or ulimit value into the nice field.

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@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/9b51a4d0343cbf55. Report an issue: GitHub.