user service '{name}' names unknown builtin '{builtin_name}'

Error message

user service '{name}' names unknown builtin '{builtin_name}'; available: {}

What it means

When `builtin = "<name>"` is given, the name must match one of the known built-in service definitions (listed in BUILTIN_NAMES). An unknown builtin name fails parsing, with the error listing all valid built-ins.

Source

Thrown at src/system/user_services.rs:104

            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) => {
                bail!("user service '{name}' must set `command` or `builtin`")
            }
            (Some(builtin_name), None) => {
                let Some(definition) = builtin(builtin_name) else {
                    bail!(
                        "user service '{name}' names unknown builtin '{builtin_name}'; available: {}",
                        BUILTIN_NAMES.join(", ")
                    );
                };
                description.get_or_insert_with(|| definition.description.to_string());
                restart.get_or_insert(definition.restart);
                nice = definition.nice;
                match executable {
                    Some(exe) => Some(
                        std::iter::once(quote_program(&exe.to_string_lossy()))
                            .chain(definition.args.iter().map(|arg| arg.to_string()))
                            .collect::<Vec<_>>()
                            .join(" "),
                    ),
                    None => {
                        unresolved = Some(
                            "no durable mise executable; install mise on this host first"
                                .to_string(),

View on GitHub (pinned to afd2eddd3a)

Solutions

Replace `builtin` with one of the names listed in the error message (BUILTIN_NAMES.join(", "))
Check spelling/casing of the builtin name
If no builtin fits, use a custom `command` instead

Example fix

// before
[[bootstrap.linux.user_services]]
name = "sync"
builtin = "syncthind"

// after
[[bootstrap.linux.user_services]]
name = "sync"
builtin = "syncthing"

Defensive patterns

Strategy: validation

Validate before calling

const BUILTIN_NAMES: &[&str] = &[
    // list from the error message's available builtins
];
fn validate_builtin(s: &UserServiceConfig) -> Result<(), String> {
    if let Some(b) = &s.builtin {
        if !BUILTIN_NAMES.contains(&b.as_str()) {
            return Err(format!("unknown builtin '{}' for service '{}'", b, s.name));
        }
    }
    Ok(())
}

Prevention

Copy builtin names from the error's available list or docs
Watch for builtin renames across mise versions

When it happens

Trigger: `builtin` set to a string not present in `BUILTIN_NAMES`, so `builtin(builtin_name)` returns None at src/system/user_services.rs:104.

Common situations: Typo in a builtin name; guessing builtin names without checking the available list; built-in renamed between versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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