What causes "--retain-bytes must be greater than 0" in astrid-runtime/astrid?

Pass --retain-bytes with a value >= 1, or omit the flag entirely if byte-based retention is not wanted

--retain-bytes must be greater than 0

Error message

--retain-bytes must be greater than 0

What it means

In `run_prune` (crates/astrid-cli/src/commands/audit.rs:110), the CLI rejects `--retain-bytes 0` with bail! before issuing the AuditPrune request. A zero byte cap would prune everything, so it is treated as an invalid argument rather than a no-op.

Source

Thrown at crates/astrid-cli/src/commands/audit.rs:110

    let format = ValueFormat::parse(&args.format);
    if format.is_pretty() {
        print_stats_pretty(&stats, &health);
    } else {
        emit_structured(&AuditStatsOutput { stats, health }, format)?;
    }
    Ok(if degraded {
        ExitCode::from(2)
    } else {
        ExitCode::SUCCESS
    })
}

async fn run_prune(args: &AuditPruneArgs) -> Result<ExitCode> {
    if args.retain_entries == 0 {
        bail!("--retain-entries must be at least 1");
    }
    if args.retain_bytes == Some(0) {
        bail!("--retain-bytes must be greater than 0");
    }
    let mut client = connect_as_active_agent().await?;
    let body = into_result(
        client
            .request(AdminRequestKind::AuditPrune {
                retain_entries: args.retain_entries,
                retain_bytes: args.retain_bytes,
            })
            .await?,
    )?;
    let AdminResponseBody::AuditPruned(result) = body else {
        bail!("unexpected response from kernel: {body:?}");
    };
    let format = ValueFormat::parse(&args.format);
    if format.is_pretty() {
        print_prune_pretty(&result);
    } else {
        emit_structured(&result, format)?;

View on GitHub (pinned to affd8760f4)

Solutions

Pass --retain-bytes with a value >= 1, or omit the flag entirely if byte-based retention is not wanted
In scripts, guard the computed budget before invoking the CLI
Use a large sentinel value rather than 0 if the intent is 'keep nearly nothing but not everything'

Example fix

// before
astrid audit prune --retain-bytes 0
// after
# omit the flag (no byte limit) or use a positive value:
astrid audit prune --retain-bytes 1048576

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
if [ -n "$RETAIN_BYTES" ] && [ "$RETAIN_BYTES" -eq 0 ]; then
  echo "--retain-bytes must be greater than 0 (or omit the flag)" >&2; exit 64
fi
astrid audit prune --retain-bytes "${RETAIN_BYTES:+$RETAIN_BYTES}"

Try / catch

match astrid::commands::audit::run_prune(&args).await {
    Ok(code) => code,
    Err(e) if e.to_string().contains("--retain-bytes") => {
        eprintln!("invalid retention: {e:#}");
        ExitCode::from(64)
    }
    Err(e) => return Err(e),
}

Prevention

Omit --retain-bytes entirely for no byte cap instead of passing 0
Guard computed byte budgets in scripts so they cannot be 0
Document that 0 means 'invalid' (would prune everything), not 'unlimited'
Add unit tests for prune argument validation

When it happens

Trigger: Running `astrid-cli audit prune --retain-bytes 0` (Option<u64> set to Some(0)), typically from a script computing a byte budget that ended up 0.

Common situations: Automation computing a retention byte budget from a quota that is currently 0; typo passing 0 instead of omitting the flag (None = unlimited by bytes); confusion between 'no limit' and 'zero limit'.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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