jdx/mise · error

brew-cask: failed to generate {} completions from {}: {}

Error message

brew-cask: failed to generate {} completions from {}: {}

What it means

To produce shell completions for a cask, mise executes the staged executable with the stanza's args, sets SHELL to the target shell, and adds a shell parameter (e.g. --zsh) derived from shell_parameter_format. This error fires when that subprocess either cannot be spawned (wrapped spawn failure) or exits non-zero; the message embeds the executable path and the trimmed stderr of the run. It means the completion-generation contract between the cask stanza and the binary failed at runtime.

Source

Thrown at src/system/packages/brew/cask.rs:4354

    command.env("SHELL", shell.name());
    let (shell_args, shell_env) = completion_shell_parameter(
        completion.shell_parameter_format.as_deref(),
        shell,
        executable,
    );
    command.args(shell_args);
    for (key, value) in shell_env {
        command.env(key, value);
    }
    let output = command.output().wrap_err_with(|| {
        format!(
            "failed to generate {} completions from {}",
            shell.name(),
            executable.display()
        )
    })?;
    if !output.status.success() {
        bail!(
            "brew-cask: failed to generate {} completions from {}: {}",
            shell.name(),
            executable.display(),
            String::from_utf8_lossy(&output.stderr).trim()
        );
    }
    Ok(String::from_utf8_lossy(&output.stdout).into_owned())
}

fn completion_shell_parameter(
    format: Option<&str>,
    shell: CompletionShell,
    executable: &Path,
) -> (Vec<String>, Vec<(String, String)>) {
    let shell_parameter = shell.parameter_name().to_string();
    match format {
        None => (vec![shell_parameter], Vec::new()),
        Some("arg") => (vec![format!("--shell={shell_parameter}")], Vec::new()),

View on GitHub (pinned to 6f52dcdf99)

Solutions

  1. Reproduce manually: run the exact staged executable with the stanza's args plus the shell flag and SHELL=<shell> set, and read the stderr the error already includes — a usage/parse error means the stanza's args or shell_parameter_format are wrong for this binary version.
  2. Fix the stanza: adjust 'args' and 'shell_parameter_format' so the binary's own completion command is invoked correctly (check the CLI's --help).
  3. If the binary depends on a runtime or env (python, node, HOME), install/provide it before running mise install, or export the needed variables.
  4. If completion generation is optional for you, remove/disable the generated-completion stanza for that cask so install proceeds without completions.
  5. Report the stanza upstream (cask metadata repo) if the CLI changed its completion interface and the stanza is stale.

Example fix

# before — stanza assumes clap-style flags but binary wants a subcommand
"generated": [{ "executable": "bin/tool", "args": ["--zsh"] }]

# after
"generated": [{ "executable": "bin/tool", "args": ["completion", "zsh"] }]
Defensive patterns

Strategy: try-catch

Validate before calling

# smoke-test completion generation before relying on install
BIN="<caskroom>/bin/tool"
SHELL=zsh "$BIN" <stanza-args> <shell-flag> >/dev/null || echo "completion generation will fail; fix stanza args"

Try / catch

let out = std::process::Command::new(&exe).args(&args).output();
match out {
    Ok(o) if o.status.success() => String::from_utf8_lossy(&o.stdout).into_owned(),
    Ok(o) => {
        // degrade gracefully: log stderr, skip completions, keep the install going
        warn!("completion generation failed: {}", String::from_utf8_lossy(&o.stderr).trim());
        None
    }
    Err(e) => { warn!("failed to spawn {}: {e}", exe.display()); None }
}

Prevention

When it happens

Trigger: Running `mise install` (or use/upgrade) of a brew-cask whose generated completion stanza invokes a binary that: rejects the completion flags used (wrong args or wrong shell_parameter_format), needs an interpreter (python/node) missing from mise's execution environment, is a macOS Mach-O binary run on an unsupported context, or crashes before emitting stdout. The non-success branch at src/system/packages/brew/cask.rs:4354 includes the binary's stderr verbatim.

Common situations: A cask stanza passes args like ["completions", "zsh"] but the shipped CLI expects `completion zsh` (singular) or only supports `--generate-completion`; upstream CLI versions that changed their completion subcommand; binaries that require HOME/XDG env vars that are unset in the install context; executables that are actually scripts with a missing shebang interpreter.

Related errors

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/ec3bf1a6007d167f. Report an issue: GitHub.