agent '{name}' `queue_directories` must not contain empty en

Error message

agent '{name}' `queue_directories` must not contain empty entries

What it means

Each entry in an agent's queue_directories list is trimmed and checked; an entry that is empty or only whitespace causes LaunchdRequest::from_toml to reject the agent (it is skipped with a warning). launchd requires every QueueDirectories entry to name a real directory, so blank entries cannot be passed through.

Source

Thrown at src/system/launchd.rs:117

}

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)
            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)"
                );
            }
        }
        Ok(Self {
            label: format!("dev.mise.{name}"),
            name,
            program,
            args: config.args,
            run_at_load: config.run_at_load,

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Remove the empty entry from queue_directories
If the directory is not yet decided, remove queue_directories entirely until it is known
Re-run mise bootstrap and verify the agent passes validation

Example fix

# before
[bootstrap.macos.launchd.agents.mailwatch]
program = "/usr/local/bin/watch"
queue_directories = ["", "/var/spool/mail"]

# after
[bootstrap.macos.launchd.agents.mailwatch]
program = "/usr/local/bin/watch"
queue_directories = ["/var/spool/mail"]

Defensive patterns

Strategy: validation

Validate before calling

python3 - <<'EOF'
import tomllib,sys
c=tomllib.load(open('mise.toml','rb'))
for name,agent in (c.get('bootstrap',{}).get('macos',{}).get('launchd',{}).get('agents',{}) or {}).items():
    for d in agent.get('queue_directories',[]) or []:
        if not d.strip(): sys.exit(f'agent {name} has empty queue_directories entry')
EOF

Prevention

Keep queue_directories lists tight; drop empty slots from templating
Omit queue_directories until the real paths are known
Treat empty entries as bugs — launchd needs concrete directories

When it happens

Trigger: Writing queue_directories = ["", "/var/spool/mail"] or queue_directories = [" "] in a [bootstrap.macos.launchd.agents.<name>] table.

Common situations: Trailing commas or list templating that yields empty slots; placeholders pending real paths; copy-paste leaving an empty line inside the TOML array.

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/486ac6ba8e68a05e. Report an issue: GitHub.