agent name '{name}' must contain only letters, numbers, '.',

Error message

agent name '{name}' must contain only letters, numbers, '.', '_', or '-'

What it means

LaunchdRequest::from_toml validates the agent name — the TOML key under [bootstrap.macos.launchd.agents]. valid_name requires it to be non-empty and contain only ASCII letters, digits, '.', '_', '-'. The name becomes part of the launchd label dev.mise.<name>, so characters that cannot round-trip through launchd/plist handling are rejected up front. Note the aggregation layer logs this as a warning and skips the agent.

Source

Thrown at src/system/launchd.rs:104

pub enum LaunchdState {
    Loaded,
    Unloaded,
    Differs,
    Missing,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LaunchdStatus {
    pub request: LaunchdRequest,
    pub path: PathBuf,
    pub loaded: bool,
    pub state: LaunchdState,
}

impl LaunchdRequest {
    pub 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 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)

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Rename the agent key to use only alphanumerics plus '.', '_', '-'
Keep human descriptions out of the key; put them in a comment or docs
Re-run mise bootstrap and verify the agent loads with label dev.mise.<name>

Example fix

# before
[bootstrap.macos.launchd.agents."sync worker"]
program = "/usr/local/bin/sync"

# after
[bootstrap.macos.launchd.agents.sync-worker]
program = "/usr/local/bin/sync"

Defensive patterns

Strategy: validation

Validate before calling

python3 - <<'EOF'
import tomllib,sys,re
c=tomllib.load(open('mise.toml','rb'))
for name in (c.get('bootstrap',{}).get('macos',{}).get('launchd',{}).get('agents',{}) or {}):
    if not re.fullmatch(r'[A-Za-z0-9._-]+',name): sys.exit(f'invalid launchd agent name: {name!r}')
EOF

Prevention

Use slug-style agent names (letters, digits, dot, underscore, hyphen)
Keep labels out of keys; launchd labels get the dev.mise. prefix automatically
Re-run mise bootstrap after renaming and check the warning log for skipped agents

When it happens

Trigger: Keying an agent as "sync worker" (space), "backup/nightly" (slash), a non-ASCII name, or an empty key inside [bootstrap.macos.launchd.agents].

Common situations: Human-readable labels with spaces used as agent names; copying systemd unit names that contain '@' or '.'-adjacent separators; localized agent names; names pasted from URLs or paths.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/76f0a4f2801489bc. Report an issue: GitHub.