invalid bootstrap service name '{name}': use at most 255 ASC

Error message

invalid bootstrap service name '{name}': use at most 255 ASCII letters, digits, '.', '_', '@', ':', or '-'

What it means

Thrown by `normalize_unit_name` when a bootstrap service name is empty, longer than 255 bytes, starts with '-', or contains characters outside ASCII letters, digits, '.', '_', '@', ':', '-'. These mirror systemd's own unit-name constraints; names without a dot get a default suffix appended (e.g. .service).

Source

Thrown at src/system/services.rs:618

    [
        "/usr/bin/systemctl",
        "/bin/systemctl",
        "/run/current-system/sw/bin/systemctl",
    ]
    .into_iter()
    .map(PathBuf::from)
    .find(|path| path.is_file())
}

fn normalize_unit_name(name: &str) -> Result<String> {
    if name.is_empty()
        || name.len() > 255
        || name.starts_with('-')
        || !name
            .chars()
            .all(|character| character.is_ascii_alphanumeric() || "_.@:-".contains(character))
    {
        bail!(
            "invalid bootstrap service name '{name}': use at most 255 ASCII letters, digits, '.', '_', '@', ':', or '-'"
        );
    }
    if name.contains('.') {
        Ok(name.to_string())
    } else {
        Ok(format!("{name}.service"))
    }
}

fn describe_current(active_state: &str, unit_file_state: &str, need_daemon_reload: bool) -> String {
    format!(
        "{active_state}; {unit_file_state}{}",
        if need_daemon_reload {
            "; daemon reload needed"
        } else {
            ""
        }

View on GitHub (pinned to afd2eddd3a)

Solutions

Rename the service key to only ASCII letters, digits, '.', '_', '@', ':' or '-', without a leading '-'
Shorten the name to 255 bytes or fewer
Include a dot (or let mise append the default suffix) so systemd gets a proper unit name, e.g. `myapp.service` or just `myapp`

Example fix

# before
[bootstrap.services."-my app/worker"]
state = "running"
# after
[bootstrap.services.myapp-worker]
state = "running"

Defensive patterns

Strategy: validation

Validate before calling

fn valid_unit_name(name: &str) -> bool {
    !name.is_empty() && name.len() <= 255 && !name.starts_with('-')
        && name.chars().all(|c| c.is_ascii_alphanumeric() || "_.@:-".contains(c))
}

Prevention

Keep service keys short and ASCII: letters, digits, dots, underscores
Never use leading dashes, spaces, slashes or backslashes in unit names
Let mise append the default suffix by using dot-free simple names
Generate names programmatically? enforce the charset/length rule at generation time

When it happens

Trigger: A `[bootstrap.services.<key>]` whose key violates the charset/length rules: leading dash, spaces or slashes in the name, Unicode characters, or names over 255 bytes.

Common situations: Using a descriptive sentence or path as the service key; Windows-derived names with backslashes; very long generated names; typos like '-myunit'.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/9263ca99f36521b7. Report an issue: GitHub.