brew-cask: structured symlink globs must use staged_path

Error message

brew-cask: structured symlink globs must use staged_path

What it means

Brew-cask structured symlink steps that use glob sources must anchor them at the staged application path (FlightPathBase::StagedPath). A glob with a different base (e.g. appdir or an absolute base) is rejected, since the library only expands and constrains globs within the staged bundle.

Source

Thrown at src/system/packages/brew/cask/flight.rs:945

        FlightGuard::IfExists(path) => {
            Ok(resolve_flight_path_with_context(cask, path, staged_path, appdir)?.exists())
        }
        FlightGuard::UnlessExists(path) => {
            Ok(!resolve_flight_path_with_context(cask, path, staged_path, appdir)?.exists())
        }
    }
}

pub(super) fn flight_symlink_sources(
    cask: &Cask,
    source: &FlightPath,
    source_glob: bool,
    staged_path: &Path,
    appdir: &Path,
) -> Result<Vec<PathBuf>> {
    if source_glob {
        if source.base != FlightPathBase::StagedPath {
            bail!("brew-cask: structured symlink globs must use staged_path");
        }
        let pattern = expand_flight_template(cask, &source.path, staged_path, appdir);
        return expand_staged_glob(staged_path, &pattern);
    }
    Ok(vec![resolve_flight_path_with_context(
        cask,
        source,
        staged_path,
        appdir,
    )?])
}

pub(super) fn create_flight_symlink(source: &Path, target: &Path, sudo: FlightSudo) -> Result<()> {
    match sudo {
        FlightSudo::Never => file::make_symlink(source, target).map(|_| ()),
        FlightSudo::IfNeeded => make_symlink_elevating(source, target),
        FlightSudo::Always => sudo::run("/bin/ln", &symlink_command_args(source, target), &[]),
    }

View on GitHub (pinned to afd2eddd3a)

Solutions

Change the source's base to staged_path in the flight step definition.
If the file lives outside the staged bundle, drop source_glob and use a non-glob source path with the appropriate base.
Restructure the step so the glob matches files inside the staged bundle and a separate step links/copies outward.

Example fix

// before
source: { base: "appdir", path: "plugins/*.bundle", glob: true }
// after
source: { base: "staged_path", path: "MyApp.app/Contents/PlugIns/*.bundle", glob: true }

Defensive patterns

Strategy: validation

Validate before calling

if source_glob && source.base != FlightPathBase::StagedPath {
    return Err(eyre!("globs must be declared with base staged_path"));
}

Prevention

Declare glob sources with base=staged_path and staged-relative paths.
Use non-glob sources for anything outside the staged bundle.
Validate cask flight definitions against the schema before publishing.

When it happens

Trigger: FlightStep::Copy or FlightStep::Symlink with source_glob=true whose source.base is not StagedPath — e.g. a cask definition specifying a glob relative to appdir or an absolute path instead of the staged bundle.

Common situations: Cask authors writing globs intended to match already-installed files in the appdir rather than staged contents; copy-pasting a non-glob source (which may use other bases) into a glob-based step; misunderstanding that globs are staged_path-relative by design.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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