What causes "--retain-entries must be at least 1" in astrid-runtime/astrid?

Pass --retain-entries with a value >= 1

--retain-entries must be at least 1

Error message

--retain-entries must be at least 1

What it means

In `run_prune` (crates/astrid-cli/src/commands/audit.rs:107), the CLI validates that `--retain-entries` is at least 1 before sending the AuditPrune request; passing 0 is rejected with bail!. Retaining zero entries would delete the entire audit log, so the CLI forbids it as an argument guard.

Source

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

        other => bail!("unexpected response from kernel: {other:?}"),
    };
    let degraded = stats.degraded || health.degraded;
    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() {

View on GitHub (pinned to affd8760f4)

Solutions

Pass --retain-entries with a value >= 1
If the value comes from a variable/script, clamp it: RETAIN=$(( RETAIN < 1 ? 1 : RETAIN ))
If the goal is to delete everything, use the appropriate purge/wipe command instead of prune

Example fix

// before
retain_entries=0  # or computed as 0
astrid audit prune --retain-entries "$retain_entries"
// after
retain_entries=$(( ${retain_entries:-1} < 1 ? 1 : ${retain_entries:-1} ))
astrid audit prune --retain-entries "$retain_entries"

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
retain=${RETAIN_ENTRIES:-1}
if [ "$retain" -lt 1 ]; then
  echo "--retain-entries must be at least 1" >&2; exit 64
fi
astrid audit prune --retain-entries "$retain"

Try / catch

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

Prevention

Clamp computed retention counts to >= 1 in automation before invoking the CLI
Never pass 0 for retain-entries; use the dedicated purge command if you truly want to wipe
Add CI checks on scripts that compute retention values
Remember omitting the flag uses its default; only pass explicit positive values

When it happens

Trigger: Running `astrid-cli audit prune --retain-entries 0` (or a value that parses to 0) from a script or shell where the count was computed as 0 (e.g. empty variable, failed wc -l).

Common situations: Automation passing a computed retention count that evaluates to 0; typos like `--retain-entries=0`; intent to fully wipe the log, which this command intentionally disallows.

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/f0d0a3a6d463318a. Report an issue: GitHub.