astrid-runtime/astrid · error

shuttle member ' ' is bytes, exceeding the -byte limit

Error message

shuttle member '{}' is {size} bytes, exceeding the {MAX_MEMBER_BYTES}-byte limit

What it means

`unpack` reads each member's declared size from the tar header and refuses any member larger than `MAX_MEMBER_BYTES`, mirroring the pack-side limit. The size is read explicitly (failing if the header is unreadable) so header corruption cannot silently bypass the cap.

Solutions

1. Re-pack the capsule with the current tool version so all members fit `MAX_MEMBER_BYTES`.
2. Verify the archive integrity (signature/checksum) — an inflated header usually means tampering or corruption.
3. If content genuinely needs more space, increase `MAX_MEMBER_BYTES` consistently on both pack and unpack sides.

// check declared sizes before unpack with an archive listing
// tar -tvf x.shuttle  -> verify every member < MAX_MEMBER_BYTES
fn within_limit(size: u64) -> bool { size <= MAX_MEMBER_BYTES }

fn within_member_limit(size: u64) -> bool { size <= MAX_MEMBER_BYTES }

if let Err(e) = shuttle::unpack(archive, dest) {
    if e.to_string().contains("exceeding") {
        eprintln!("member exceeds limit; verify archive integrity or repack: {e}");
    }
}

When it happens

Trigger: Calling `shuttle::unpack` on an archive whose member header declares `size() > MAX_MEMBER_BYTES`, or whose size field is unreadable (which yields the related 'unreadable member size' error).

Common situations: A tampered archive with inflated headers; installing a capsule packed with a larger limit by a different version of the tool; corruption from a bad transfer.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• shuttle member ' ' is bytes ( ), exceeding the -byte…
• capsule archive contains duplicate path
• Distro.lock exceeds 1 MB limit
• Distro.sig exceeds size limit
• Distro.toml exceeds 1 MB limit

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/e02954d65c73a7d7. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/distro/shuttle.rs:224

        // nodes, FIFOs, sockets, and any other special entry type are
        // rejected: a `.shuttle` only ever legitimately carries regular
        // files, so an exotic type is either corruption or an attack.
        if !et.is_file() {
            bail!(
                "malicious shuttle detected: unsupported entry type for '{}' \
                 (only regular files are allowed)",
                entry_path.display()
            );
        }

        // A corrupt/undecodable size field must fail closed, not be coerced
        // to 0 — otherwise header corruption silently bypasses the cap.
        let size = entry
            .header()
            .size()
            .context("malicious shuttle detected: unreadable member size")?;
        if size > MAX_MEMBER_BYTES {
            bail!(
                "shuttle member '{}' is {size} bytes, exceeding the {MAX_MEMBER_BYTES}-byte limit",
                entry_path.display()
            );
        }

        let out_path = dest.join(&entry_path);
        if let Some(parent) = out_path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        entry
            .unpack(&out_path)
            .with_context(|| format!("failed to unpack {}", out_path.display()))?;
    }
    Ok(())
}

/// The archive-relative path of a capsule member: `capsules/<name>.capsule`.
pub(crate) fn capsule_member_path(name: &str) -> String {

View on GitHub (pinned to affd8760f4)