wasmerio/wasmer · error

failed to unpack (with parent) {}: {e}

Error message

failed to unpack (with parent) {}: {e}

What it means

try_unpack_targz in lib/cli/src/utils/unpack.rs extracts a downloaded .tar.gz archive with the `tar` crate. When `ar.unpack(target_path)` fails (an entry cannot be read, decompressed, or written to disk), it wraps the io error in this message identifying the archive path and whether the parent directory was preserved. It is a wrapper around tar extraction, not a download failure.

Source

Thrown at lib/cli/src/utils/unpack.rs:69

        lzma_rs::xz_decompress(&mut bufread, &mut decomp).map_err(|e| {
            anyhow::anyhow!(
                "failed to unpack (try_decode_xz) {}: {e}",
                target_targz_path.display()
            )
        })?;

        let cursor = std::io::Cursor::new(decomp);
        let mut ar = tar::Archive::new(cursor);
        if strip_toplevel {
            unpack_sans_parent(ar, target_path).map_err(|e| {
                anyhow::anyhow!(
                    "failed to unpack (sans parent) {}: {e}",
                    target_targz_path.display()
                )
            })
        } else {
            ar.unpack(target_path).map_err(|e| {
                anyhow::anyhow!(
                    "failed to unpack (with parent) {}: {e}",
                    target_targz_path.display()
                )
            })
        }
    };

    try_decode_gz().or_else(|e1| {
        try_decode_xz()
            .map_err(|e2| anyhow::anyhow!("could not decode gz: {e1}, could not decode xz: {e2}"))
    })?;

    Ok(Path::new(&target_targz_path).to_path_buf())
}

pub fn unpack_with_parent<R>(mut archive: tar::Archive<R>, dst: &Path) -> Result<(), anyhow::Error>
where
    R: std::io::Read,

View on GitHub (pinned to 8c4b9ee9d3)

Solutions

  1. Delete the cached archive file and re-download it; a truncated gzip stream is the most common cause.
  2. Check the target directory exists and is writable (mkdir -p, fix permissions).
  3. Verify the archive integrity manually: `tar -tzf <file>` should list entries without errors.
  4. Free disk space / shorten the target path if extraction fails mid-write.
  5. Check the inner `{e}` message for the specific entry and I/O error to pinpoint the cause.

Example fix

// before: reusing a possibly stale cache
download(url, &target_targz_path)?;
try_unpack_targz(&target_targz_path, &dir, false)?;
// after: remove stale cache first
if target_targz_path.exists() {
    std::fs::remove_file(&target_targz_path)?;
}
download(url, &target_targz_path)?;
std::fs::create_dir_all(&dir)?;
try_unpack_targz(&target_targz_path, &dir, false)?;
Defensive patterns

Strategy: validation

Validate before calling

// verify archive is readable and target dir writable before unpacking
fn precheck(archive: &Path, target: &Path) -> anyhow::Result<()> {
    let f = std::fs::File::open(archive)?;
    let mut gz = flate2::read::GzDecoder::new(f);
    let mut tar = tar::Archive::new(&mut gz);
    tar.entries()?.count(); // fails fast on corrupt archive
    anyhow::ensure!(target.is_dir(), "target dir missing: {}", target.display());
    let probe = target.join(".wprobe");
    std::fs::write(&probe, b"")?;
    std::fs::remove_file(&probe)?;
    Ok(())
}

Try / catch

match try_unpack_targz(&archive, &dir, false) {
    Ok(p) => p,
    Err(e) if e.to_string().contains("failed to unpack") => {
        std::fs::remove_file(&archive).ok(); // drop corrupt cache
        re_download_and_unpack(&archive, &dir)?
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

Trigger: Calling try_unpack_targz on a corrupt or truncated .tar.gz, on an archive containing entries whose paths escape or cannot be created under target_path, or when the target directory is unwritable (permissions, disk full, path too long).

Common situations: Interrupted download leaving a partial archive cached locally; antivirus or another process locking files in the target dir on Windows; extracting an archive built with unusual entry permissions or symlinks into a read-only install directory.

Related errors

AI-assisted analysis of wasmerio/wasmer@8c4b9ee9d3 (2026-09-01). Data as JSON: /api/errors/ca8db211ae51f762. Report an issue: GitHub.