unexpected bottle layout for

Error message

unexpected bottle layout for {name}: missing {name}/{pkg_version} in archive

What it means

When pouring a bottle, prepare_bottle extracts the archive and expects Homebrew's standard layout: a top-level `<name>/<pkg_version>/` directory containing the keg. If that directory is absent after extraction, the bottle's layout doesn't match what the API metadata promised, and mise bails rather than installing a keg at an unknown location.

Solutions

Delete the cached bottle and retry so the archive is re-downloaded
Verify the bottle URL/tarball manually (`tar tf bottle.tar.gz | head`) to confirm it contains `<name>/<version>/`
Check for a mise or homebrew-core/tap update — a formula/pkg-version layout change may need a newer mise

Defensive patterns

Strategy: retry

Validate before calling

tar -tzf bottle.tar.gz | grep -q "^$name/$version/" || echo "bottle layout mismatch"

Try / catch

try {
  applyBrewPackage(name);
} catch (e) {
  if (String(e).includes('unexpected bottle layout')) {
    clearBottleCache();
    applyBrewPackage(name); // retry with a fresh download
  } else throw e;
}

Prevention

Clear the bottle cache after network interruptions or proxy changes
Keep mise updated so bottle metadata handling matches current Homebrew artifacts
Verify bottles come from the official ghcr.io source, not a stale mirror

When it happens

Trigger: prepare_bottle extracts a downloaded bottle tarball and prepared.staged_keg does not exist — the archive lacks the `<name>/<pkg_version>` top-level directory (corrupt/truncated download, wrong bottle served, upstream layout change, or version mismatch between API metadata and artifact).

Common situations: Proxy or mirror serving stale/partial bottle tarballs; API bottle metadata out of sync with the uploaded artifact; cache holding a damaged download.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/7ca4f252efa1c740. Report an issue: GitHub.

Appendix: source

Thrown at src/system/packages/brew/pour.rs:399

        staging,
        keg_only: rf.formula.keg_only_for_target(),
    };

    // bottle tarballs contain <name>/<pkg_version>/...
    pr.set_message("extract".to_string());
    crate::file::untar(
        tarball,
        prepared.staging.path(),
        ExtractionFormat::TarGz,
        &ExtractOptions {
            strip_components: 0,
            pr: Some(pr),
            preserve_mtime: true,
        },
    )
    .wrap_err_with(|| format!("failed to extract bottle for {name}"))?;
    if !prepared.staged_keg.exists() {
        bail!(
            "unexpected bottle layout for {name}: missing {name}/{} in archive",
            prepared.pkg_version
        );
    }

    // ":any_skip_relocation" skips binary linkage relocation, but Homebrew
    // still replaces placeholders in text files. On Linux, bottles built by
    // Homebrew < 5.1.15 are incorrectly tagged and still need ELF linkage
    // relocation (brew applies the same version check in
    // extend/os/linux/bottle_specification.rb).
    let skip_linkage = bottle.cellar == ":any_skip_relocation"
        && (cfg!(target_os = "macos")
            || bottled_by_homebrew_at_least(&prepared.staged_keg, (5, 1, 15)));
    pr.set_message("relocate".to_string());
    let report = relocate::relocate_keg(&prepared.staged_keg, name, skip_linkage)?;
    // arm64 macOS kills binaries whose signature doesn't match; Linux ELF
    // files have no signatures to fix
    if cfg!(target_os = "macos") && !report.changed_machos.is_empty() {

View on GitHub (pinned to 533346cc37)