brew-cask: invalid command_wrapper environment name '{key}'

Error message

brew-cask: invalid command_wrapper environment name '{key}'

What it means

Each key of a command_wrapper's 'env' map becomes an environment variable in the generated bash wrapper, so mise validates it with is_shell_env_name: first character must be '_' or an ASCII letter, all remaining characters '_' or ASCII alphanumeric. Keys with dashes, dots, spaces, or a leading digit are rejected with the offending key named in the message.

Source

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

                .iter()
                .map(|arg| {
                    arg.as_str()
                        .map(str::to_string)
                        .ok_or_else(|| eyre!("brew-cask: command_wrapper args must be strings"))
                })
                .collect::<Result<Vec<_>>>()
        })
        .transpose()?
        .unwrap_or_default();
    let env = options
        .get("env")
        .map(|env| {
            env.as_object()
                .ok_or_else(|| eyre!("brew-cask: command_wrapper env must be an object"))?
                .iter()
                .map(|(key, value)| {
                    if !is_shell_env_name(key) {
                        bail!("brew-cask: invalid command_wrapper environment name '{key}'");
                    }
                    value
                        .as_str()
                        .map(|value| (key.clone(), value.to_string()))
                        .ok_or_else(|| {
                            eyre!("brew-cask: command_wrapper environment values must be strings")
                        })
                })
                .collect::<Result<BTreeMap<_, _>>>()
        })
        .transpose()?
        .unwrap_or_default();
    if content.is_some() && (!args.is_empty() || !env.is_empty()) {
        bail!("brew-cask: command_wrapper args and env require executable");
    }
    Ok(Some(CommandWrapperArtifact {
        name: name.to_string(),
        target: artifact_target(value, values),

View on GitHub (pinned to 6f52dcdf99)

Solutions

Rename the variable to a valid shell identifier: MY-VAR -> MY_VAR, 1VAR -> VAR1.
If the wrapped program truly requires an odd name, pass it via 'args' or set it inside 'content' instead of the env map.
Validate env keys with the same rule in your metadata generator.

Example fix

# before
command_wrapper: [["tool", {"executable": "bin/tool", "env": {"MY-VAR": "1"}}]]

# after
command_wrapper: [["tool", {"executable": "bin/tool", "env": {"MY_VAR": "1"}}]]

Defensive patterns

Strategy: type-guard

Validate before calling

fn is_shell_env_name_like(v: &str) -> bool {
    let mut c = v.chars();
    c.next().is_some_and(|f| f == '_' || f.is_ascii_alphabetic())
        && c.all(|r| r == '_' || r.is_ascii_alphanumeric())
}

Type guard

function isShellEnvName(name) {
  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
}

Prevention

Use snake_case UPPER_SHELL_NAMES for every env key in wrapper metadata.
Reject keys containing '-', '.', or leading digits in your metadata validator.
For exotic names the program requires, set them inside 'content' instead of the env map.

When it happens

Trigger: An env map like {"MY-VAR": "1"}, {"1VAR": "x"}, or {"MY.VAR": "y"} — any key failing the character rule implemented at src/system/packages/brew/cask.rs:4678 and enforced at :5183.

Common situations: Authors copying env names that are valid elsewhere (HTTP-Proxy in launchd plists, my.tool.opts in config files) but illegal as shell identifiers; hyphenated names that silently break the generated wrapper; metadata written from a JSON schema without identifier constraints.

Related errors

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