brew-cask: cannot adopt '{}': existing artifact is not ident

Error message

brew-cask: cannot adopt '{}': existing artifact is not identical to the cask artifact

What it means

When adopting an existing artifact into a cask-managed location, Homebrew optionally verifies that the on-disk artifact is byte-identical (fingerprint match) to the cask's staged source. If the fingerprints differ it refuses the adoption to avoid clobbering a user-modified or different-version file.

Source

Thrown at src/system/packages/brew/cask/mod.rs:1020

    // only by name relative to that descriptor. Nothing below resolves a
    // pathname for the application directory, so a post-validation replacement
    // of any appdir component — even by the same uid — cannot redirect the
    // copy, rename, removal, permission repair, or quarantine steps.
    let parent = ensure_trusted_appdir(
        logical_target
            .parent()
            .ok_or_else(|| eyre!("brew-cask: app target has no parent directory"))?,
    )?;
    let name = logical_target
        .file_name()
        .ok_or_else(|| eyre!("brew-cask: app target has no filename"))?
        .to_owned();
    if adopt && exists_at(&parent.fd, &name)? {
        if verify_adopt {
            let source_fingerprint = cask_target_fingerprint(&source)?;
            let target_fingerprint = cask_target_fingerprint(&logical_target)?;
            if source_fingerprint != target_fingerprint {
                bail!(
                    "brew-cask: cannot adopt '{}': existing artifact is not identical to the cask artifact",
                    logical_target.display()
                );
            }
        }
        return Ok(true);
    }

    ditto(&source, &caskroom_app)?;
    // Suffix hashes stay derived from the logical path so temporary and backup
    // names are stable across runs.
    let name_hash = crate::hash::hash_to_str(&logical_target.display().to_string());
    let tmp_name = replace_bundle_extension(&name, &format!("mise-tmp-{name_hash}"));
    let old_name = replace_bundle_extension(&name, &format!("mise-old-{name_hash}"));
    remove_all_at(&parent.fd, &tmp_name)?;
    ditto_into(&caskroom_app, &parent.fd, &tmp_name)?;
    activate_app_at(
        &parent,

View on GitHub (pinned to afd2eddd3a)

Solutions

Bring the existing artifact to the same version/content as the cask (re-download or update) and retry with --adopt
Remove or back up the differing existing artifact and install fresh without adopt
Use `--no-adopt`-equivalent flow (skip adoption) if you want to keep the existing artifact untouched

Example fix

// shell
# before
brew install --adopt iterm2   # existing app is v3.5, cask ships v3.4
# after
brew uninstall --force iterm2 && brew install --adopt iterm2

Defensive patterns

Strategy: validation

Validate before calling

if exists && cask_target_fingerprint(&source)? != cask_target_fingerprint(&target)? {
    eprintln!("existing artifact differs; adopt will fail — update or remove it first");
}

Try / catch

match install_adopt(req).await {
    Err(e) if e.to_string().contains("not identical to the cask artifact") => {
        // back up target, reinstall fresh, or skip adopt
        Err(e)
    }
    r => r,
}

Prevention

Ensure the on-disk app version matches the cask version before adopting
Avoid in-place edits to app bundles you plan to adopt
Compare versions via `brew info` before `--adopt`

When it happens

Trigger: adopt mode with verify_adopt enabled and the target path already exists; `cask_target_fingerprint(source) != cask_target_fingerprint(logical_target)` — the existing file differs from the staged artifact (different version or modified content).

Common situations: Users who manually installed/updated an app to a newer version than the cask, then run `brew install --adopt`; files edited in place (license patches, plist tweaks) breaking fingerprint equality.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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