user service name '{name}' must contain only letters, number

Error message

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

What it means

User service names are validated in `from_toml_with_executable` with a slightly stricter character set than systemd units (no `@` allowed here): only letters, numbers, `.`, `_`, and `-`. Names failing `valid_name` are rejected before the service definition is registered.

Source

Thrown at src/system/user_services.rs:81

}

impl UserServiceRequest {
    pub(crate) fn from_toml(
        name: String,
        config: ServiceTomlConfig,
        origin: Option<ResourceOrigin>,
    ) -> Result<Self> {
        Self::from_toml_with_executable(name, config, origin, durable_mise_executable())
    }

    fn from_toml_with_executable(
        name: String,
        config: ServiceTomlConfig,
        origin: Option<ResourceOrigin>,
        executable: Option<PathBuf>,
    ) -> Result<Self> {
        if !valid_name(&name) {
            bail!(
                "user service name '{name}' must contain only letters, numbers, '.', '_', or '-'"
            );
        }
        if config.masked {
            bail!("user service '{name}' cannot be masked; use `state = \"absent\"` to remove it");
        }
        if config.on_change != super::services_common::ServiceChangeAction::default() {
            bail!("user service '{name}': `on_change` only applies to system services");
        }
        let mut description = config.description;
        let mut restart = config.restart;
        let mut nice = None;
        let mut unresolved = None;
        let command = match (config.builtin.as_deref(), config.command.as_deref()) {
            (Some(_), Some(_)) => {
                bail!("user service '{name}' sets both `builtin` and `command`; choose one")
            }
            (None, None) => {

View on GitHub (pinned to afd2eddd3a)

Solutions

Rename the service to use only letters, numbers, `.`, `_`, or `-` (e.g. `my-app-dev`).
Replace `@` templated-style names with a plain hyphenated name.
Remove surrounding whitespace from the TOML key.

Example fix

# before
[services."api:dev"]

# after
[services.api-dev]

Defensive patterns

Strategy: validation

Validate before calling

fn valid_service_name(name: &str) -> bool {
    !name.is_empty()
        && name.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))
}
assert!(valid_service_name("api-dev"));

Prevention

Restrict service names to `[A-Za-z0-9._-]` when generating config from templates.
Avoid `@` and `:` even though systemd allows some of them — this layer is stricter.
Sanitize user/branch names before embedding them in service names.

When it happens

Trigger: Defining a user service in mise.toml (a `[services]`/user-services TOML block parsed via `from_toml_with_executable`) whose name key contains whitespace, `/`, `:`, `@`, or other special characters.

Common situations: Names copied from systemd templated units including `@`; names with spaces like `"my app"`; environment suffixes written with `:` (e.g. `api:dev`).

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/5d886a0f84993d70. Report an issue: GitHub.