Hmbown/CodeWhale · error · anyhow::Error

The Codewhale service returned an unexpectedly large respons

Error message

The Codewhale service returned an unexpectedly large response

What it means

The CLI cloud transport caps any Codewhale service response at MAX_RESPONSE_BYTES (256 KiB) by reading MAX_RESPONSE_BYTES+1 bytes and bailing if the body exceeds the cap. This bounds memory and rejects responses that cannot be legitimate small JSON API payloads (device-code start, token, me, key acknowledgements).

Source

Thrown at crates/cli/src/cloud.rs:249

        if let Some(token) = request.bearer {
            builder = builder.bearer_auth(token);
        }
        if let Some(body) = request.body {
            builder = builder
                .header(reqwest::header::CONTENT_TYPE, "application/json")
                .body(body);
        }
        let response = builder
            .send()
            .context("could not reach the Codewhale service")?;
        let status = response.status().as_u16();
        let mut body = Vec::new();
        response
            .take(MAX_RESPONSE_BYTES + 1)
            .read_to_end(&mut body)
            .context("failed to read the Codewhale service response")?;
        if body.len() as u64 > MAX_RESPONSE_BYTES {
            bail!("The Codewhale service returned an unexpectedly large response");
        }
        Ok(CloudResponse { status, body })
    }
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct DeviceStart {
    device_code: String,
    user_code: String,
    verification_uri: String,
    verification_uri_complete: String,
    expires_in: u64,
    interval: u64,
}

#[derive(Deserialize)]
struct MeResponse {

View on GitHub (pinned to 0c42157ee5)

Solutions

Run the same request with curl -H 'Accept: application/json' against the configured API base and inspect Content-Type and size of what comes back.
If a proxy/captive portal is injecting HTML, fix network egress or bypass the proxy for the API host.
Verify the configured API base URL is the real Codewhale account API origin, not a web front end.
If the genuine API response grew past 256 KiB, report it — the payload contract for these endpoints is small JSON.

Example fix

# before
--api-base https://corp-portal.example.com

# after (point at the real API origin)
--api-base https://api.codewhale.net

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight the API base before any cloud call
let resp = reqwest::Client::new().get(format!("{api_base}/api/me"))
    .header(ACCEPT, "application/json").send().await?;
if resp.headers().get(CONTENT_TYPE).map(|v| v.as_bytes().starts_with(b"application/json")).unwrap_or(false) == false {
    anyhow::bail!("API base is not serving JSON; check proxies/DNS");
}

Try / catch

match transport.execute(req).await {
    Ok(r) => r,
    Err(e) if e.to_string().contains("unexpectedly large response") => {
        // response cannot be a valid small JSON payload — fix egress/proxy, do not retry
        anyhow::bail!("cloud API egress broken (oversized non-JSON response): {e}")
    }
    Err(e) => Err(e),
}

Prevention

Verify egress to the API host returns JSON (curl) in new network environments.
Exclude the API host from captive-portal/proxy paths.
Pin --api-base to the real API origin.

When it happens

Trigger: A cloud API endpoint (e.g. /api/cli/device/token, /api/me, /api/model-keys/...) answering with a body larger than 256 KiB — typically an HTML error page from a gateway, a captive-portal response, or a misrouted endpoint returning bulk data.

Common situations: Corporate proxy or captive portal intercepting the request and returning a large interstitial page, wrong --api-base pointing at a website instead of the JSON API, or a service-side incident serving oversized error documents.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/e1817bc930954a4a. Report an issue: GitHub.