mas app IDs must be numeric ADAM IDs (e.g. "mas:497799835")

Error message

mas app IDs must be numeric ADAM IDs (e.g. "mas:497799835")

What it means

mise validates package names for each system package manager before resolving them. For the macOS App Store 'mas' manager, names must be numeric ADAM IDs (e.g. 497799835), not app names or slugs. validate_package_name in src/system/mod.rs:1575 bails out when packages::mas::is_adam_id(name) returns false.

Source

Thrown at src/system/mod.rs:1575

fn is_opaque_package_manager(mgr: &str) -> bool {
    is_brew_manager(mgr) || mgr == "mas"
}

fn normalize_use_spec_package_name<'a>(mgr: &str, name: &'a str) -> eyre::Result<&'a str> {
    if mgr == "mas"
        && let Some(name) = name.strip_suffix("@latest")
    {
        if name.is_empty() {
            bail!("invalid system package spec: expected '<manager>:<package>[@version]'");
        }
        return Ok(name);
    }
    Ok(name)
}

fn validate_package_name(mgr: &str, name: &str) -> eyre::Result<()> {
    if mgr == "mas" && !packages::mas::is_adam_id(name) {
        bail!("mas app IDs must be numeric ADAM IDs (e.g. \"mas:497799835\")");
    }
    Ok(())
}

pub(crate) fn brew_taps_from_config(config: &Config) -> IndexMap<String, String> {
    brew_taps_from_config_files(&config.config_files)
}

fn brew_taps_from_config_files(config_files: &ConfigMap) -> IndexMap<String, String> {
    let mut brew_taps: IndexMap<String, String> = IndexMap::new();
    for cf in config_files.values().rev() {
        if let Some(sys) = cf.bootstrap_config() {
            for (tap, url) in sys.brew.taps {
                brew_taps.insert(tap, url);
            }
        }
    }
    brew_taps

View on GitHub (pinned to afd2eddd3a)

Solutions

Look up the app's numeric ADAM ID (e.g. via `mas search <name>`, or the number in the App Store URL) and use it as the package name
Ensure the name contains only digits, e.g. mas = ["497799835"] instead of ["Xcode"]
If you meant a Homebrew cask, move the entry to the brew manager instead of mas

Example fix

// before (mise.toml)
[system_packages]
mas = ["Xcode"]
// after
[system_packages]
mas = ["497799835"]

Defensive patterns

Strategy: validation

Validate before calling

fn is_valid_mas_id(name: &str) -> bool { !name.is_empty() && name.chars().all(|c| c.is_ascii_digit()) }
// check every mas entry before writing it to mise.toml

Type guard

fn as_mas_adam_id(name: &str) -> Option<&str> {
    let id = name.strip_prefix("mas:").unwrap_or(name);
    (!id.is_empty() && id.chars().all(|c| c.is_ascii_digit())).then_some(id)
}

Prevention

Always source mas IDs with `mas search <app>` or the numeric ID in the App Store URL
Keep human-readable app names out of mas package entries; store them as comments
Add a lint in CI that asserts all mas entries match ^[0-9]+$

When it happens

Trigger: Declaring a system_packages entry with manager 'mas' whose name is not purely numeric, e.g. name = "Xcode" or "slack" instead of an ADAM ID; calling the package install/resolve path with validate_package_name("mas", name) where name fails packages::mas::is_adam_id.

Common situations: Writing mise.toml [system_packages] with mas = ["xcode"] using human-readable app names; copying app names from the Mac App Store UI instead of the numeric ID from the mas CLI; pasting the full 'mas:497799835' form where only the bare ID is expected.

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/3c700b084417e19c. Report an issue: GitHub.