astrid-runtime/astrid · error

shuttle member ' ' is bytes ( ), exceeding the -byte…

Error message

shuttle member '{}' is {} bytes ({}), exceeding the {MAX_MEMBER_BYTES}-byte per-member limit

What it means

During `pack`, each staged file member of a `.shuttle` capsule is size-checked against `MAX_MEMBER_BYTES`. If a staged source file exceeds that per-member limit, packing aborts so no single oversized member can be embedded in the archive.

Solutions

1. Remove or exclude the oversized file from the staged capsule directory.
2. Compress or split the file so it fits under `MAX_MEMBER_BYTES`.
3. If the limit is legitimately too small for your content, raise `MAX_MEMBER_BYTES` (or `within_member_limit`) in the crate and repack.

Example fix

// before
ShuttleContent::File(huge_artifact)  // 10 MB staged file
// after
// exclude or compress:
ShuttleContent::File(compressed_artifact) // under MAX_MEMBER_BYTES

let len = std::fs::metadata(src)?.len();
if len > MAX_MEMBER_BYTES {
    eprintln!("{} is {} bytes; limit is {}", src.display(), len, MAX_MEMBER_BYTES);
    std::process::exit(1);
}

match pack(&staging, &out) {
    Err(e) if e.to_string().contains("per-member limit") => {
        eprintln!("drop or compress the oversized member: {e:#}")
    }
    other => other?,
}

When it happens

Trigger: Calling `pack` (directly or through `run` CLI) when a staged `ShuttleContent::File` source's `fs::metadata(src).len()` exceeds `MAX_MEMBER_BYTES`. Detected by tests like `pack_rejects_oversized_file_member`.

Common situations: Accidentally staging a build artifact, VM image, or large binary in the capsule staging directory; a generated file ballooning after a code change.

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 limit
• 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/ccc879ae52530b96. Report an issue: GitHub.

Appendix: source

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

            header.set_mtime(0);
            header.set_uid(0);
            header.set_gid(0);
            header.set_mode(0o644);
            header.set_entry_type(tar::EntryType::Regular);

            match &entry.content {
                ShuttleContent::Bytes(bytes) => {
                    header.set_size(bytes.len() as u64);
                    header.set_cksum();
                    tar.append_data(&mut header, &entry.path, bytes.as_slice())
                        .with_context(|| format!("failed to append {} to shuttle", entry.path))?;
                },
                ShuttleContent::File(src) => {
                    let metadata = std::fs::metadata(src).with_context(|| {
                        format!("failed to stat staged capsule {}", src.display())
                    })?;
                    if !within_member_limit(metadata.len()) {
                        bail!(
                            "shuttle member '{}' is {} bytes ({}), exceeding the \
                             {MAX_MEMBER_BYTES}-byte per-member limit",
                            src.display(),
                            metadata.len(),
                            entry.path
                        );
                    }
                    header.set_size(metadata.len());
                    header.set_cksum();
                    let mut file = std::fs::File::open(src).with_context(|| {
                        format!("failed to open staged capsule {}", src.display())
                    })?;
                    tar.append_data(&mut header, &entry.path, &mut file)
                        .with_context(|| format!("failed to append {} to shuttle", entry.path))?;
                },
            }
        }

View on GitHub (pinned to affd8760f4)