zeroclaw-labs/zeroclaw · error

fal.ai response exceeds the 1 MiB size limit

Error message

fal.ai response exceeds the 1 MiB size limit

What it means

After a successful fal.ai generation, read_fal_success_body reads the JSON response through response_body::read_bounded with FAL_RESPONSE_LIMIT_BYTES = 1 MiB. If the provider's success payload crosses that cap, the bounded reader sets the overflowed flag and this error fires, so the tool fails instead of buffering an unbounded body. The usual cause is a fal app configured to return images inline (base64 data URIs) instead of URLs, which inflates the JSON far past 1 MiB.

Source

Thrown at crates/zeroclaw-tools/src/image_gen.rs:169

    model: &str,
    prompt: &str,
) -> String {
    format!(
        "Image generated successfully.\n\
         File: {path_display}\n\
         Size: {size_kb} KB\n\
         Model: {model}\n\
         Prompt: {prompt}\n\
         [IMAGE:{path_display}]",
    )
}

async fn read_fal_success_body(response: reqwest::Response) -> anyhow::Result<Vec<u8>> {
    let body = response_body::read_bounded(response, Some(FAL_RESPONSE_LIMIT_BYTES))
        .await
        .context("Failed to read fal.ai response")?;
    if body.overflowed {
        anyhow::bail!("fal.ai response exceeds the 1 MiB size limit");
    }
    Ok(body.bytes)
}

async fn read_fal_error_text(response: reqwest::Response) -> anyhow::Result<String> {
    response_body::read_text(response, Some(FAL_ERROR_LIMIT_BYTES))
        .await
        .map(|(text, _)| text)
}

async fn read_generated_image_body(response: reqwest::Response) -> anyhow::Result<Vec<u8>> {
    let body = response_body::read_bounded(response, Some(GENERATED_IMAGE_LIMIT_BYTES))
        .await
        .context("Failed to read generated image bytes")?;
    if body.overflowed {
        anyhow::bail!(
            "Generated image exceeds the {} MiB size limit",
            GENERATED_IMAGE_LIMIT_BYTES / (1024 * 1024)

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Configure the fal.ai model/app to return a hosted URL (fal media storage) rather than inline base64 data, and keep response_format URL-based.
2. Verify you are calling the intended endpoint with the right FAL key so unexpected bulky success bodies (or misrouted responses) are not being read.
3. If a legitimate workflow truly needs >1 MiB JSON, the limit is the internal constant FAL_RESPONSE_LIMIT_BYTES in crates/zeroclaw-tools/src/image_gen.rs; changing it is a code-level decision, not a runtime config.

Example fix

# before (fal app output mode: inline/data URI)
{"images":[{"data":"iVBORw0KGgo..."}]}      # >1 MiB JSON -> rejected

# after (fal app output mode: hosted URL)
{"images":[{"url":"https://v3.fal.media/files/..."}]}  # small JSON -> accepted

match generate(request).await {
    Err(e) if e.to_string().contains("1 MiB size limit") => {
        // fal app is returning inline base64: switch the app/output mode to hosted URLs and retry once
        regenerate_with_url_output_mode(request).await
    }
    other => other,
}

When it happens

Trigger: Generating with a fal.ai model/app whose output mode embeds base64 image data or data: URIs directly in the response JSON, or whose metadata payloads are enormous; a 1 MiB+ JSON body on a 2xx response triggers the bail. The bounded-reader test fal_success_body_rejects_oversized_chunked_response pins this behavior.

Common situations: Switching a fal app to inline/base64 output (e.g. data URI mode or b64_json-style fields), requesting very high prompt/metadata detail that bloats the JSON, or pointing the tool at a custom fal endpoint that returns bulky payloads.

Related errors

• Generated image exceeds the {} MiB size limit
• Generated image URL must be a non-empty URL without whitespa
• Generated image URL must use HTTPS
• Generated image URL userinfo is not allowed
• Generated image URL host must not end with a dot

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/e7160b100868b2a5. Report an issue: GitHub.