brew-cask:{}: git only_path must name a directory within the

Error message

brew-cask:{}: git only_path must name a directory within the checkout

What it means

After the traversal checks, mise canonicalizes clone_dir/only_path and requires that it exists, stays inside the canonicalized clone root, and is a directory. If the path resolves outside the checkout (e.g. via a symlink) or is not a directory, the git-only_path staging is aborted. Note a missing path raises the sibling 'only_path does not exist' error instead; this one fires for out-of-tree or non-directory targets.

Source

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

        || only_path
            .components()
            .any(|component| matches!(component, Component::ParentDir | Component::Prefix(_)))
    {
        bail!(
            "brew-cask:{}: git only_path must stay within the checkout",
            cask.token
        );
    }
    let clone_root = clone_dir.canonicalize()?;
    let source = clone_dir.join(only_path).canonicalize().wrap_err_with(|| {
        format!(
            "brew-cask:{}: git only_path does not exist: {}",
            cask.token,
            only_path.display()
        )
    })?;
    if !source.starts_with(&clone_root) || !source.is_dir() {
        bail!(
            "brew-cask:{}: git only_path must name a directory within the checkout",
            cask.token
        );
    }
    Ok(source)
}

pub(super) async fn fetch_archive(cask: &Cask, pr: Option<&dyn SingleReport>) -> Result<PathBuf> {
    let filename = archive_filename(&cask.url)
        .ok_or_else(|| eyre!("brew-cask:{}: URL has no file name", cask.token))?;
    let cache_dir = crate::dirs::CACHE.join("system-brew").join("casks");
    file::create_dir_all(&cache_dir)?;
    let url_hash = &hash::hash_sha256_to_str(&cask.url)[..12];
    let archive = cache_dir.join(format!(
        "{}-{}-{url_hash}-{filename}",
        cask.token, cask.version
    ));
    if !archive.exists() {

View on GitHub (pinned to afd2eddd3a)

Solutions

Change only_path to name a directory inside the repository checkout.
If only_path must reference a single file, update the cask definition to stage that file differently (e.g. use an archive URL instead of git).
Verify the directory exists on the branch being cloned (check cask url_specs.branch) and adjust branch or path.

Example fix

// before
"only_path": "dist/tool.bin"
// after (directory containing the artifacts)
"only_path": "dist"

Defensive patterns

Strategy: validation

Validate before calling

// ensure the path exists and is a directory in the cloned repo before install
const p = require('child_process');
const out = p.execSync(`git ls-tree -d --name-only HEAD ${relPath}`).toString().trim();
if (!out) throw new Error(`only_path '${relPath}' is not a directory in the repo`);

Prevention

Point only_path at directories, not individual files.
Pin the cask's branch and verify the directory exists on that branch.
Re-check only_path after any repository restructure.

When it happens

Trigger: Installing a git-URL cask whose only_path points at a regular file rather than a directory, or at a symlink resolving outside the clone root; also triggered if clone_dir/only_path escapes the checkout after canonicalization.

Common situations: A cask authored for an older layout where only_path named a file; repo restructure moved/renamed the directory; a symlinked path in the checkout resolving to an external location.

Related errors

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