jdx/mise · error

vfox plugin archive contains a reserved or unsafe path

Error message

vfox plugin archive contains a reserved or unsafe path

What it means

During archive validation for vfox plugins, each path component of every tar entry must be a normal component (no absolute paths, `..`, `.` traversal). Additionally, no component may contain backslashes or colons, or be named `.git` or the packslip state file (case-insensitively). This prevents path traversal and overwriting of mise's internal state during extraction.

Source

Thrown at src/plugins/packslip.rs:228

    for entry in archive.entries()? {
        let entry = entry?;
        ensure!(
            matches!(
                entry.entry_type(),
                jdx_tar::EntryType::File | jdx_tar::EntryType::Directory
            ),
            "vfox plugin archive contains a link or special file"
        );
        let path = entry.path()?;
        for component in path.components() {
            if component == Component::CurDir {
                continue;
            }
            let Component::Normal(name) = component else {
                bail!("vfox plugin archive contains an unsafe path");
            };
            let name = name.to_string_lossy();
            ensure!(
                !name.contains(['\\', ':'])
                    && !name.eq_ignore_ascii_case(".git")
                    && !name.eq_ignore_ascii_case(STATE_FILE),
                "vfox plugin archive contains a reserved or unsafe path"
            );
        }
    }
    Ok(())
}

pub(crate) fn validate_layout(path: &Path) -> Result<()> {
    ensure!(
        path.join("metadata.lua").is_file(),
        "vfox plugin archive must contain metadata.lua at its root"
    );
    Ok(())
}

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Repackage the archive with relative paths: `tar -czf plugin.tar.gz -C <staging-dir> .`.
2. Delete the `.git` directory (and any state-file-named files) before creating the archive.
3. Sanitize entry names to use forward slashes and remove traversal components in the packaging script.
4. If the archive is untrusted, do not attempt to work around the check — obtain the plugin from a trusted source.

Example fix

// before: tar -czf plugin.tar.gz /home/me/plugin   (absolute paths, includes .git)
// after
rm -rf plugin/.git && tar -czf plugin.tar.gz -C /home/me/plugin .

# shell: reject absolute paths, .., backslashes, .git before installing
tar -tzf plugin.tar.gz | grep -E '(^/|(^|/)\.\.(/|$)|\\|(^|/)\.git(/|$))' && echo 'REJECTED: unsafe paths' || echo 'OK'

When it happens

Trigger: Installing a vfox plugin whose archive contains entries with absolute paths, `..` components, `\` or `:` in a name, a `.git` directory, or a file matching the reserved state-file name.

Common situations: Archives built on Windows with backslash separators, tarballs that embed absolute paths (`tar -C /` mistakes), packaging scripts that accidentally include the `.git` directory, or malicious/tampered plugin archives.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• vfox plugin archive contains an unsafe path
• content-level SLSA verification rejected unsafe archive path
• vfox plugin archive contains a link or special file
• [dotfiles]."{}": target is not a safe OCI path
• brew-cask: invalid {kind} '{value}'

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