brew-cask: command_wrapper has unsupported option {}

Error message

brew-cask: command_wrapper has unsupported option {}

What it means

Thrown when a cask command_wrapper artifact supplies option keys outside the supported set {content, executable, args, env}. The parser collects the unrecognized keys and bails with the joined list so the cask definition can be corrected.

Source

Thrown at src/system/packages/brew/cask/artifacts.rs:204

        .ok_or_else(|| eyre!("brew-cask: command_wrapper requires a command name"))?;
    let name_path = Path::new(name);
    if name_path.file_name().and_then(|name| name.to_str()) != Some(name)
        || matches!(name, "." | "..")
    {
        bail!("brew-cask: command_wrapper requires a command name without path components");
    }
    let options = values
        .get(1)
        .and_then(Value::as_object)
        .ok_or_else(|| eyre!("brew-cask: command_wrapper requires options"))?;
    let mut unsupported = options
        .keys()
        .filter(|key| !matches!(key.as_str(), "content" | "executable" | "args" | "env"))
        .cloned()
        .collect::<Vec<_>>();
    unsupported.sort();
    if !unsupported.is_empty() {
        bail!(
            "brew-cask: command_wrapper has unsupported option {}",
            unsupported.join(", ")
        );
    }
    let content = options
        .get("content")
        .and_then(Value::as_str)
        .map(str::to_string);
    let executable = options
        .get("executable")
        .and_then(Value::as_str)
        .map(str::to_string);
    match (content.is_some(), executable.is_some()) {
        (false, false) => {
            bail!("brew-cask: command_wrapper requires content or executable")
        }
        (true, true) => {
            bail!("brew-cask: command_wrapper requires content or executable, not both")

View on GitHub (pinned to afd2eddd3a)

Solutions

Remove or rename the listed unsupported options to one of content, executable, args, env.
Check spelling: 'args' not 'arguments', 'content' not 'contents'.
Confirm the cask syntax matches the version this parser supports; open the cask definition and prune unknown keys.

Example fix

// before
["mytool", {"executable": "mytool", "arguments": ["--help"]}]
// after
["mytool", {"executable": "mytool", "args": ["--help"]}]

Defensive patterns

Strategy: validation

Validate before calling

const CW_KEYS: [&str; 4] = ["content", "executable", "args", "env"];
fn cw_keys_ok(keys: &[&str]) -> Vec<&str> {
    keys.iter().filter(|k| !CW_KEYS.contains(k)).cloned().collect()
}
assert!(cw_keys_ok(&["executable"]).is_empty());

Try / catch

match result {
    Err(e) if e.to_string().contains("unsupported option") => {
        // parse the listed keys from the message and fix the cask definition
    }
    other => other?,
}

Prevention

Keep a whitelist constant of allowed command_wrapper keys in your config generator
Spell-check option names against docs: content, executable, args, env
Validate cask JSON with a schema before parsing

When it happens

Trigger: A command_wrapper options object contains any key other than 'content', 'executable', 'args', or 'env', e.g. a typo like 'arguments', 'contents', or 'name'.

Common situations: Typos in option names; carrying over options from a different artifact type; newer/older Homebrew stanza syntax not supported by this parser version.

Related errors

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