invalid bootstrap service name

Error message

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

What it means

Bootstrap service names are validated against systemd unit-name rules: at most 255 ASCII alphanumerics plus `.`, `_`, `@`, `:`, `-`, and no leading `-`. `normalize_unit_name`, invoked when parsing service TOML, rejects any name violating this before mise derives the unit name.

Solutions

Rename the service to only ASCII letters, digits, `.`, `_`, `@`, `:`, `-` (max 255 chars, no leading `-`)
Use a valid systemd unit name including the suffix (e.g. `myapp.service`)
Sanitize any dynamically generated service names before writing config

Example fix

// before (mise.toml)
[services."dev/server"]
scope = "system"
// after
[services."dev-server.service"]
scope = "system"

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

fn is_valid_unit_name(s: &str) -> Option<&str> { let ok = !s.is_empty() && s.len() <= 255 && !s.starts_with('-') && s.chars().all(|c| c.is_ascii_alphanumeric() || "_.@:-".contains(c)); ok.then_some(s) }

Prevention

Use lowercase ASCII names with dashes or dots only
Never derive service names from paths or free-form strings without sanitizing
Keep names under 255 characters

When it happens

Trigger: Declaring a bootstrap service in mise.toml with a name containing spaces, slashes, non-ASCII characters, a leading dash, or exceeding 255 characters — parsed via `from_toml_with_origin` → `normalize_unit_name`.

Common situations: Using a descriptive name like `my app` or `dev/server` instead of the systemd unit name; pasting a path as the service name; generating names from untrusted input.

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@533346cc37 (2026-09-17). Data as JSON: /api/errors/9263ca99f36521b7. Report an issue: GitHub.

Appendix: 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 533346cc37)