jdx/mise · error · eyre::Report

{option}: '{name}' must be a plain file name (no path separa

Error message

{option}: '{name}' must be a plain file name (no path separators or parent directories)

What it means

mise validates that the `rename_exe` (and similar) backend option is a single plain file name before joining it onto the install directory. The guard `file::is_plain_file_name` rejects any value containing `/` or `\\`, or any parent/root/drive component, because such a value would place or find the binary outside the install dir (path traversal). It is thrown during install/setup of static-binary backends (ubi, http, aqua-style) when the option is first read.

Source

Thrown at src/backend/static_helpers.rs:1133

        p.file_name()
            .map(|n| {
                let name = n.to_string_lossy();
                !should_skip_file(&name, true) && glob.matches(&name)
            })
            .unwrap_or(false)
    }) {
        return Ok(Some(available.remove(idx)));
    }

    Ok(None)
}

/// Rejects `bin`/`rename_exe` names that are not plain file names (`../tool`,
/// `/abs/tool`, `bin/tool`), which would otherwise be joined onto the install
/// or search directory and place the binary outside it.
pub fn ensure_plain_bin_name(option: &str, name: &str) -> eyre::Result<()> {
    if !file::is_plain_file_name(name) {
        bail!(
            "{option}: '{name}' must be a plain file name \
             (no path separators or parent directories)"
        );
    }
    Ok(())
}

/// Rejects a configured binary path that is absolute or contains parent
/// components, while preserving the established `bin = "bin/tool"` form.
pub fn ensure_safe_relative_bin_path(option: &str, path: &str) -> eyre::Result<()> {
    if !file::is_safe_relative_path(path) {
        bail!(
            "{option}: '{path}' must be a safe relative path \
             (no absolute paths or parent directories)"
        );
    }
    Ok(())
}

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

  1. Set rename_exe to a plain file name only, e.g. rename_exe = "tool" — directories belong in the `bin` option (bin = "bin/tool"), not in rename_exe
  2. If you need the binary at a nested path, keep the nested path in `bin` and use rename_exe only for the final name change
  3. Remove any leading ./ , ../ , or absolute path from the value; both `/` and `\\` are rejected on every platform

Example fix

# before (mise.toml)
[tools.ubi]
mytool = { repo = 'org/mytool', rename_exe = 'bin/mytool-renamed' }

# after
[tools.ubi]
mytool = { repo = 'org/mytool', bin = 'bin/', rename_exe = 'mytool-renamed' }
Defensive patterns

Strategy: validation

Validate before calling

# Rust: same rule mise enforces (see file::is_plain_file_name)
fn is_plain_bin_name(s: &str) -> bool {
    !s.is_empty()
        && !s.contains('/')
        && !s.contains('\\')
        && std::path::Path::new(s).components().next()
            .map(|c| matches!(c, std::path::Component::Normal(_)))
            .unwrap_or(false)
}
assert!(is_plain_bin_name("tool"));
assert!(!is_plain_bin_name("bin/tool"));

Prevention

When it happens

Trigger: A mise.toml `[tools]` entry with e.g. `rename_exe = "../tool"`, `rename_exe = "/usr/local/bin/tool"`, or `rename_exe = "bin/tool"` (any path with separators) for a backend that calls ensure_plain_bin_name (src/backend/static_helpers.rs:591, :1048, :1087; src/backend/http.rs:409). The error surfaces as soon as the tool version is installed or the option is parsed.

Common situations: Copy-pasting a `bin = "bin/tool"` style value into `rename_exe` (the two options have different rules); migrating from a backend that allowed paths; trying to rename into a subdirectory of the install dir; values copied from Windows configs with backslashes.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/20394c91fcc3ecc5. Report an issue: GitHub.