brew-cask:{token}: Homebrew metadata exists with multiple Ca

Error message

brew-cask:{token}: Homebrew metadata exists with multiple Caskroom versions ({}); repair it with Homebrew

What it means

homebrew_installed_version requires exactly one installed Caskroom version per token. When Homebrew metadata exists but multiple version directories are present in the Caskroom, the version is ambiguous, so mise bails with the sorted version list and directs the user to Homebrew for repair.

Source

Thrown at src/system/packages/brew/cask/state.rs:83

        if file_type.is_dir() && name != ".metadata" && !name.starts_with(".mise-") {
            versions.push(name);
        }
    }
    Ok(versions)
}

pub(super) fn homebrew_installed_version(token: &str) -> Result<Option<String>> {
    if !homebrew_metadata_present(token)? {
        return Ok(None);
    }

    let versions = homebrew_installed_versions(token)?;
    match versions.as_slice() {
        [version] => Ok(Some(version.clone())),
        [] => bail!(
            "brew-cask:{token}: Homebrew metadata exists, but no installed Caskroom version was found; repair it with `brew reinstall --cask {token}`"
        ),
        versions => bail!(
            "brew-cask:{token}: Homebrew metadata exists with multiple Caskroom versions ({}); repair it with Homebrew",
            {
                let mut versions = versions.to_vec();
                versions.sort();
                versions.join(", ")
            }
        ),
    }
}

pub(super) fn ensure_homebrew_did_not_take_ownership(token: &str, stage: &Path) -> Result<()> {
    let metadata_present = match homebrew_metadata_present(token) {
        Ok(present) => present,
        Err(err) => {
            file::remove_all(stage).wrap_err_with(|| {
                format!(
                    "failed to remove mise stage after Homebrew ownership check failed: {err:#}"
                )

View on GitHub (pinned to afd2eddd3a)

Solutions

Run `brew cleanup --cask <token>` to remove stale version directories, keeping one
Run `brew reinstall --cask <token>` so Homebrew normalizes to a single installed version
If appropriate, `brew uninstall --cask <token>` fully, then reinstall via mise

Example fix

// terminal
// before: Caskroom/<token>/1.0 and Caskroom/<token>/1.1 both present
// after:
brew cleanup --cask <token>  # or brew reinstall --cask <token>

Defensive patterns

Strategy: try-catch

Validate before calling

token_dir="$($(brew --repository)/bin/brew --repository)/Caskroom/<token>"
count=$(find "$token_dir" -mindepth 1 -maxdepth 1 -type d | wc -l)
[ "$count" -le 1 ] || brew cleanup --cask <token>

Try / catch

match result {
    Ok(v) => v,
    Err(e) if e.to_string().contains("multiple Caskroom versions") => {
        run("brew cleanup --cask <token>")?; retry()
    }
    Err(e) => return Err(e),
}

Prevention

Run `brew cleanup --cask` regularly, especially after upgrades
Let Homebrew finish upgrades before running mise operations
Reinstall rather than layering installs of the same cask

When it happens

Trigger: homebrew_installed_versions(token) returns more than one entry while Homebrew metadata exists — the match arm falls through to `versions => bail!(...)`.

Common situations: Homebrew upgrade failed midway leaving old and new cask version directories; `brew cleanup` never ran after upgrades; multiple partial installs of the same cask.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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