brew-cask: nested archive depth exceeds

Error message

brew-cask: nested archive depth exceeds {MAX_NESTED_CASK_ARCHIVES}

What it means

Nested cask archive extraction is depth-limited by MAX_NESTED_CASK_ARCHIVES. After extracting a nested archive, the code re-checks the extract dir and if it still contains a single archive (i.e., another layer would need extraction), the depth budget is exhausted and this error is thrown. It guards against archives nested arbitrarily deep, which could recurse indefinitely.

Solutions

Manually unpack the artifact to inspect how many layers it has and confirm it is legitimate
Extract the outer layers yourself and stage the final payload, or fix the cask to point at a single-layer archive
Report/patch the cask definition so it references a non-recursively-nested artifact
If the nesting is legitimate, raise MAX_NESTED_CASK_ARCHIVES in the fetcher

Defensive patterns

Strategy: validation

Validate before calling

// Inspect layer count before installing
let mut depth = 0; let mut cur = downloaded.clone();
while is_archive(&cur) { cur = peek_inner(&cur)?; depth += 1; }
assert!(depth <= MAX_NESTED_CASK_ARCHIVES, "too many nested archives");

Type guard

fn within_depth(n: usize) -> bool { n <= MAX_NESTED_CASK_ARCHIVES }

Try / catch

match result {
    Err(e) if e.to_string().contains("nested archive depth") => manually_extract_outer_layers(),
    other => other?,
}

Prevention

Prefer cask artifacts that are single-layer archives
Validate artifact structure once per upstream version in CI
Avoid casks that repack archives inside archives

When it happens

Trigger: A downloaded cask archive contains an archive, which contains another archive, and so on past the MAX_NESTED_CASK_ARCHIVES limit; `extract_nested_cask_archives` (called from `extract_archive`) unwraps each layer via `extract_nested_cask_archive` and then `single_nested_cask_archive` finds yet another archive.

Common situations: Upstream ships a zip inside a tar.gz inside a dmg; a malformed or adversarial cask artifact; a newly increased nesting depth in an upstream release that outgrows the constant.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/system/packages/brew/cask/fetch.rs:341

            .to_string();
        let nested = extract_dir.with_file_name(format!(
            ".{}-nested-{depth}",
            extract_dir
                .file_name()
                .and_then(|name| name.to_str())
                .unwrap_or("cask")
        ));
        file::remove_all(&nested)?;
        file::rename(&archive, &nested)?;
        file::remove_all(extract_dir)?;
        file::create_dir_all(extract_dir)?;
        let result = extract_nested_cask_archive(&nested, extract_dir, &filename, pr);
        let cleanup = file::remove_all(&nested);
        result?;
        cleanup?;
    }
    if single_nested_cask_archive(extract_dir)?.is_some() {
        bail!("brew-cask: nested archive depth exceeds {MAX_NESTED_CASK_ARCHIVES}");
    }
    Ok(())
}

pub(super) fn single_nested_cask_archive(root: &Path) -> Result<Option<PathBuf>> {
    let mut entries = std::fs::read_dir(root)?.filter(|entry| match entry {
        Ok(entry) => entry.file_name() != "__MACOSX",
        Err(_) => true,
    });
    let Some(entry) = entries.next().transpose()? else {
        return Ok(None);
    };
    if entries.next().is_some() || !entry.file_type()?.is_file() {
        return Ok(None);
    }
    let path = entry.path();
    let filename = entry.file_name();
    let filename = filename

View on GitHub (pinned to 533346cc37)