astrid-runtime/astrid · error

mount callback response exceeds limit

Error message

mount callback response exceeds limit

What it means

write_response serializes a CallbackResponse (V1 or V2) to JSON and refuses to send it if the serialized byte length exceeds MAX_CALLBACK_FRAME_BYTES. This keeps each callback frame within the fixed length-prefix framing the socket protocol uses.

Solutions

1. Cap Read request sizes to fit within MAX_CALLBACK_FRAME_BYTES and return data in multiple reads
2. If you control the code, align the client's max read size with the kernel's MAX_CALLBACK_FRAME_BYTES constant
3. Shrink the response payload (remove embedded blobs/metadata) so serialization fits
4. Enlarge MAX_CALLBACK_FRAME_BYTES only if both kernel and provider are updated together

Example fix

// before
let data = fs.read(path, 0, 64 * 1024 * 1024)?;
// after
let data = fs.read(path, 0, MAX_CALLBACK_FRAME_BYTES - FRAME_OVERHEAD)?;

fn fits_in_callback_frame(bytes_len: usize) -> bool {
    bytes_len <= MAX_CALLBACK_FRAME_BYTES
}
// before issuing a large Read, clamp the request size:
let read_len = read_len.min(MAX_CALLBACK_FRAME_BYTES - FRAME_OVERHEAD);

match result {
    Err(e) if e.to_string() == "mount callback response exceeds limit" => {
        eprintln!("response too large: reduce read size or chunk reads");
    }
    other => other?,
}

When it happens

Trigger: An operation returns a response whose JSON serialization is larger than MAX_CALLBACK_FRAME_BYTES — typically a Read response carrying a huge data blob — and write_response (from handle_connection) rejects it before writing the length prefix.

Common situations: A reader requests more bytes than the frame limit allows in one Read reply; MAX_CALLBACK_FRAME_BYTES was shrunk in config/constant while clients still request big reads; a response accidentally embeds large debug data.

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

• filesystem payload exceeds limit
• FUSE service control response exceeds the bounded frame size
• mount callback frame exceeds limit
• mount callback response is too large
• Admin request timed out after

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

Appendix: source

Thrown at crates/astrid-kernel/src/storage_mount.rs:681

        StorageFilesystemOperationV2::Rename { from, to, replace } => {
            StorageFilesystemOperationV1::Rename { from, to, replace }
        },
        StorageFilesystemOperationV2::Sync => StorageFilesystemOperationV1::Sync,
    })
}

#[cfg(any(unix, windows))]
async fn write_response(
    stream: &mut LocalStream,
    response: CallbackResponse,
) -> Result<(), io::Error> {
    let bytes = match response {
        CallbackResponse::V1(response) => serde_json::to_vec(&response),
        CallbackResponse::V2(response) => serde_json::to_vec(&response),
    }
    .map_err(io::Error::other)?;
    if bytes.len() > MAX_CALLBACK_FRAME_BYTES {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            "mount callback response exceeds limit",
        ));
    }
    let length = u32::try_from(bytes.len()).map_err(|_| {
        io::Error::new(
            io::ErrorKind::InvalidData,
            "mount callback response is too large",
        )
    })?;
    stream.write_all(&length.to_be_bytes()).await?;
    stream.write_all(&bytes).await?;
    stream.flush().await
}

async fn dispatch_request(
    kernel: &Kernel,
    state: &StorageMountLeaseState,

View on GitHub (pinned to affd8760f4)