GCS download stalled: no data received for {chunk_timeout:?}

Error message

GCS download stalled: no data received for {chunk_timeout:?} while downloading {file}

What it means

While streaming the GCS response body to disk, download_file wraps chunk reads in tokio::time::timeout. If no chunk arrives within chunk_timeout, it aborts with this error naming the timeout duration and target file. It prevents a hung connection from blocking the caller forever.

Source

Thrown at crates/codegen/xai-grok-shell/src/agent/session_registry_client.rs:386

            anyhow::bail!("GCS download failed: {}", gcs_response.status());
        }
        if let Some(parent) = dest.parent() {
            tokio::fs::create_dir_all(parent).await?;
        }
        let mut out = tokio::fs::File::create(dest)
            .await
            .context("create dest file")?;
        let chunk_timeout = std::time::Duration::from_secs(60);
        loop {
            match tokio::time::timeout(chunk_timeout, gcs_response.chunk()).await {
                Ok(Ok(Some(chunk))) => {
                    tokio::io::AsyncWriteExt::write_all(&mut out, &chunk)
                        .await
                        .context("write chunk to disk")?;
                }
                Ok(Ok(None)) => break,
                Ok(Err(e)) => return Err(e).context("read GCS chunk"),
                Err(_) => anyhow::bail!(
                    "GCS download stalled: no data received for {chunk_timeout:?} \
                     while downloading {file}"
                ),
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── UpdateRequest wire shapes ────────────────────────────────────────────
    //
    // The writer split relies on two distinct update payloads being sent at
    // different times:
    //

View on GitHub (pinned to bc7f02eddd)

Solutions

Retry download_file; a fresh request usually gets a working connection
Increase chunk_timeout if downloads legitimately pause on slow links
Check network path (VPN, proxy, firewall) for idle-connection resets
Verify the object size with a HEAD request; retry with range requests for very large objects

Defensive patterns

Strategy: retry

Try / catch

for attempt in 0..3 {
    match download_file(&client, &url, &dest).await {
        Ok(()) => break,
        Err(e) if e.to_string().contains("stalled") && attempt < 2 => {
            tokio::time::sleep(Duration::from_secs(2u64.pow(attempt))).await;
        },
        Err(e) => return Err(e),
    }
}

Prevention

Retry stalled downloads with exponential backoff
Tune chunk_timeout to fit the slowest expected network
Avoid transfers over known-unstable links (VPNs, mobile) for large artifacts

When it happens

Trigger: Calling download_file when the GCS connection stalls: the body stream yields nothing within the configured chunk_timeout (the select on the stream errors on the timeout branch).

Common situations: Flaky corporate networks or mobile links dropping packets mid-transfer, GCS connections throttled or silently dropped by middleboxes, extremely slow signed-URL endpoints, or very large files over an unstable VPN.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/257ee1a511b25a8a. Report an issue: GitHub.