exceeded the bounded protocol response size

Error message

{provider_name} exceeded the bounded protocol response size

What it means

The storage runner invokes a native storage provider as a child process and reads its response with a hard cap of MAX_PROVIDER_RESPONSE_BYTES (reading cap+1 bytes to detect overflow). If the provider emits more bytes than the bound, the child is killed and the command fails rather than buffering unbounded output. This bounds memory use and treats oversized output as a protocol violation.

Solutions

Fix the provider to write only the compact V1 JSON response to stdout and send logs to stderr.
Check the provider version — upgrade to a build that respects the bounded protocol.
Re-run with the provider's verbose/debug mode off; ensure nothing wraps stdout (e.g. progress spinners).

Example fix

// before (provider)
println!("DEBUG state={:?}", state);  // extra bytes on stdout
println!("{}", serde_json::to_string(&resp)?);

// after (provider)
eprintln!("DEBUG state={:?}", state); // logs to stderr
println!("{}", serde_json::to_string(&resp)?);

Defensive patterns

Strategy: try-catch

Validate before calling

// provider side: keep stdout to the single V1 JSON response only
let body = serde_json::to_vec(&resp)?;
assert!(body.len() <= MAX_PROVIDER_RESPONSE_BYTES, "response too large");

Try / catch

match run_storage_command(args).await {
    Err(e) if e.to_string().contains("bounded protocol response size") => {
        eprintln!("Provider wrote too much to stdout; check provider version/logs-on-stderr.");
    }
    other => other?,
}

Prevention

Providers must log to stderr, never stdout.
Test providers against the size bound before deploying.
Keep provider plugins up to date with the V1 protocol spec.

When it happens

Trigger: A native provider binary writes a response larger than MAX_PROVIDER_RESPONSE_BYTES to stdout — e.g. a buggy provider dumping debug output, emitting an unintended payload, or not respecting the V1 response schema size expectations.

Common situations: Third-party or homegrown provider plugins that print logs to stdout instead of stderr; providers echoing the entire request; corrupted/looping provider output.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at crates/astrid-cli/src/commands/storage.rs:142

        .context("native provider stdin is unavailable")?;
    serde_json::to_writer(&mut stdin, &request).context("encode native provider request")?;
    stdin
        .write_all(b"\n")
        .context("terminate native provider request")?;
    drop(stdin);
    let stdout = child
        .stdout
        .take()
        .context("native provider stdout is unavailable")?;
    let mut response_bytes = Vec::new();
    stdout
        .take(MAX_PROVIDER_RESPONSE_BYTES + 1)
        .read_to_end(&mut response_bytes)
        .context("read native provider response")?;
    if response_bytes.len() as u64 > MAX_PROVIDER_RESPONSE_BYTES {
        let _ = child.kill();
        let _ = child.wait();
        bail!("{provider_name} exceeded the bounded protocol response size");
    }
    let status = child.wait().context("wait for native storage provider")?;
    if !status.success() {
        bail!("{provider_name} exited without a successful protocol response: {status}");
    }
    let response: StorageProviderResponseV1 =
        serde_json::from_slice(&response_bytes).context("decode native provider response")?;
    validate_response(provider_name, &request, &response, &required_capabilities)?;
    render_response(response.outcome)
}

fn provider_operation(
    command: StorageCommand,
) -> Result<(StorageProviderOperationV1, Vec<StorageProviderCapabilityV1>)> {
    Ok(match command {
        StorageCommand::Mount(args) => {
            let view = args.view()?;
            let access = if args.access(&view) == "read-only" {

View on GitHub (pinned to affd8760f4)