BoundaryML/baml · error · ApiError

Transport error

Error message

Transport error: {0}

What it means

This is the Display message of ApiError::Transport in the BAML trace publisher. It wraps a reqwest::Error, meaning the HTTP request to the BAML cloud tracing API (used when publishing trace events or uploading BAML source) failed at the transport layer before a response was received: DNS resolution failure, TCP/TLS connect failure, or connection reset. The library throws it because the collector endpoint could not be reached at all.

Solutions

1. Verify network connectivity to the collector host (curl the URL from the same machine).
2. Check BAML_URL / endpoint env vars for typos or stale hosts.
3. Fix DNS/proxy settings (HTTPS_PROXY, corporate CA certs) in the runtime environment.
4. Enable retries/backoff for publishing, or disable trace export if telemetry is not required.

Example fix

// before
baml_client.tracing.disable()
// after (guarded, non-fatal publish)
match publisher.publish(event) {
    Err(ApiError::Transport(e)) => log::warn!("trace transport failed: {e}"),
    _ => {}
}

// before enabling trace export
curl -sS -o /dev/null -w "%{http_code}" "$BAML_URL/health" || echo "collector unreachable"

fn is_transport_err(e: &ApiError) -> bool { matches!(e, ApiError::Transport(_)) }

match publisher.publish(ev) {
    Err(ApiError::Transport(e)) => { log::warn!("transport: {e}"); retry_with_backoff(); }
    Err(e) => log::error!("publish failed: {e}"),
    Ok(_) => {}
}

When it happens

Trigger: The reqwest client fails to send the request or receive any response: DNS failure for the collector host, network unreachable, TLS handshake failure, proxy misconfigured, or connection dropped mid-request while sending trace events to the BAML API.

Common situations: Running BAML in an offline/air-gapped CI environment, corporate firewall or proxy blocking the collector host, BAML_URL/BAML_SECRET pointing at a wrong or unreachable host, VPN disconnected, or DNS misconfiguration in containers/K8s.

Related errors

• baml.fetch_as: HTTP request failed: HTTP
• Failed to fetch media
• Failed to fetch media bytes
• Failed to fetch media
• Failed to fetch

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/4162f9b8ad3b970d. Report an issue: GitHub.

Appendix: source

Thrown at engine/baml-runtime/src/tracingv2/publisher/publisher.rs:192

                    body: body_str,
                });
            }

            // D) happy path: 2xx → attempt to parse into T
            serde_json::from_slice::<TEndpoint::Response<'resp>>(&bytes)
                .map_err(ApiError::Deserialize)
        };

        match timeout(timeout_duration, fut).await {
            Ok(res) => res,
            Err(_) => Err(ApiError::Timeout(timeout_duration)),
        }
    }
}

#[derive(thiserror::Error, Debug)]
pub enum ApiError {
    #[error("Transport error: {0}")]
    Transport(reqwest::Error),
    #[error("HTTP error: {status} {body}")]
    Http {
        status: reqwest::StatusCode,
        body: String,
    },
    #[error("Failed to deserialize response: {0}")]
    Deserialize(serde_json::Error),
    #[error("Request timed out after {0:?}")]
    Timeout(Duration),
}

impl TypeLookup for RuntimeAST {
    fn type_lookup(&self, name: &str) -> Option<Arc<baml_rpc::BamlTypeId>> {
        self.ast.type_lookup(name)
    }

    fn function_lookup(&self, name: &str) -> Option<Arc<baml_rpc::ast::tops::BamlFunctionId>> {

View on GitHub (pinned to bd85ce9dee)