jdx/mise · error

command wrapper names cannot contain dots on Windows: {name:

Error message

command wrapper names cannot contain dots on Windows: {name:?}

What it means

On Windows, command wrapper names must not contain dots, because wrapper lookup and shim creation interact with Windows executable name handling (extension stripping, PATHEXT resolution), and dotted names create ambiguous or broken shim filenames. This check only fires when compiled for Windows (cfg!(windows)).

Source

Thrown at src/shims.rs:1133

pub(crate) fn command_name_without_exe_suffix(bin_name: &str) -> &str {
    let suffix = std::env::consts::EXE_SUFFIX;
    if suffix.is_empty() {
        return bin_name;
    }
    let suffix_start = bin_name.len().saturating_sub(suffix.len());
    match (bin_name.get(..suffix_start), bin_name.get(suffix_start..)) {
        (Some(name), Some(actual_suffix)) if actual_suffix.eq_ignore_ascii_case(suffix) => name,
        _ => bin_name,
    }
}

fn validate_wrapper_name(name: &str) -> Result<()> {
    if name.is_empty() || name == "." || name == ".." || name.contains('/') || name.contains('\\') {
        bail!("invalid command wrapper name: {name:?}");
    }
    if cfg!(windows) && name.contains('.') {
        bail!("command wrapper names cannot contain dots on Windows: {name:?}");
    }
    Ok(())
}

fn validate_wrapper_names<'a>(names: impl IntoIterator<Item = &'a String>) -> Result<()> {
    let mut normalized = HashSet::new();
    for name in names {
        validate_wrapper_name(name)?;
        if cfg!(macos) && !normalized.insert(name.to_lowercase()) {
            bail!("command wrapper names collide on macOS after case normalization: {name:?}");
        }
    }
    Ok(())
}

/// Resolve the mise executable that Unix symlink shims should target.
///
/// Snap exposes applications through `/snap/bin`, where each command is a symlink to the

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Rename the wrapper to a dot-free identifier (e.g. `terraform-fmt` instead of `terraform.fmt`).
2. Use hyphens or underscores in place of dots in the wrapper name.
3. Keep the dotted name only for the underlying command path, not the wrapper name.
4. If you need platform parity, conditionally define wrapper names per OS in your config tooling.

Example fix

// before (mise.toml, Windows)
[wrapper]
"terraform.fmt" = "terraform fmt"

// after
[wrapper]
"terraform-fmt" = "terraform fmt"

// bash: on Windows, reject dotted wrapper names before writing config
if [[ "$(uname -s)" == MINGW* || "$(uname -s)" == CYGWIN* ]]; then
  [[ "$name" == *.* ]] && echo "Windows: wrapper names cannot contain dots: $name" && exit 1
fi

When it happens

Trigger: On Windows, declaring a wrapper name like `my.tool` or `python3.12` in the command wrapper configuration or via `mise wrapper add my.tool ...`.

Common situations: Porting a mise.toml with wrappers from macOS/Linux to Windows where names like `terraform.fmt` were legal on Unix; versioned command names containing dots.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• invalid command wrapper name: {name:?}
• Unknown shim mode
• windows_script_interpreter: {interpreter:?} must be a plain
• artifactbundle must be true, false, 1, or 0, got {value}
• install_command must be a non-empty string

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