What causes "invalid OCI layer path {}" in jdx/mise?

Use a trusted base image from a reputable registry

invalid OCI layer path {}

Error message

invalid OCI layer path {}

What it means

While unpacking base-image layers, clean_layer_path sanitizes each tar entry path, rejecting components that could escape the rootfs. ParentDir ('..') and Prefix (e.g. Windows drive) components are treated as invalid and bail with the full offending path. This is a path-traversal safety guard on layer contents.

Source

Thrown at src/oci/packages.rs:291

    let magic = reader.fill_buf()?;
    if magic.starts_with(&[0x1f, 0x8b]) {
        Ok(LayerCompression::Gzip)
    } else if magic.starts_with(&[0x28, 0xb5, 0x2f, 0xfd]) {
        Ok(LayerCompression::Zstd)
    } else {
        Ok(LayerCompression::Tar)
    }
}

fn clean_layer_path(path: &Path) -> Result<PathBuf> {
    let mut out = PathBuf::new();
    for component in path.components() {
        match component {
            Component::CurDir | Component::RootDir => {}
            Component::Normal(part) => out.push(part),
            Component::ParentDir | Component::Prefix(_) => {
                bail!("invalid OCI layer path {}", path.display())
            }
        }
    }
    Ok(out)
}

fn apply_oci_whiteout(rootfs: &Path, rel: &Path) -> Result<bool> {
    let Some(name) = rel.file_name().and_then(|n| n.to_str()) else {
        return Ok(false);
    };
    let parent = rel.parent().unwrap_or_else(|| Path::new(""));
    if name == ".wh..wh..opq" {
        let dir = rootfs.join(parent);
        if dir.is_dir() {
            for entry in fs::read_dir(&dir)? {
                remove_path(&entry?.path())?;
            }
        }

View on GitHub (pinned to afd2eddd3a)

Solutions

Use a trusted base image from a reputable registry
Inspect the layer tarball (`tar -tf`) for '..' or absolute entries and rebuild it with relative paths
Re-pull the base image in case of corruption (verify digest)

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

# check a layer tarball before use
tar -tf layer.tar | grep -E '(^|/)\.\.(/|$)' && echo 'UNSAFE: parent-dir entries' || echo 'ok'

Type guard

function isSafeLayerPath(p) {
  const parts = p.split("/").filter(x => x && x !== ".");
  return !parts.includes("..") && !p.startsWith("/") && !/^[A-Za-z]:/.test(p);
}

Prevention

Pull base images only from trusted registries
Pin base images by digest
Inspect third-party layer tarballs for ../ entries before use

When it happens

Trigger: A layer tarball contains an entry whose normalized path includes '..' or a Windows prefix component, and unpack_base_layers processes it.

Common situations: Malicious or corrupted OCI base images; hand-built layer tarballs with absolute or ../ paths; third-party registries with non-conforming layer 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

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