What causes "builder error" in seanmonstar/reqwest?

Print the wrapped source: `if let Some(s) = e.source() { eprintln!("{s}"); }` — it carries the real cause (parse error, bad cert, etc.).

seanmonstar/reqwest · error · reqwest::Error

builder error

Error message

builder error

What it means

The `Kind::Builder` error, constructed by `error::builder(...)` (error.rs:344-346). It represents any failure while *building* something rather than sending it: parsing a URL string into a `Url` (into_url.rs:48), a malformed redirect `Location`, or `ClientBuilder::build()` rejecting bad TLS/identity/proxy config.

Source

Thrown at src/error.rs:345

#[derive(Debug)]
pub(crate) enum Kind {
    Builder,
    Request,
    Redirect,
    #[cfg(not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none"))))]
    Status(StatusCode, Option<hyper::ext::ReasonPhrase>),
    #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))]
    Status(StatusCode),
    Body,
    Decode,
    Upgrade,
}

// constructors

pub(crate) fn builder<E: Into<BoxError>>(e: E) -> Error {
    Error::new(Kind::Builder, Some(e))
}

pub(crate) fn body<E: Into<BoxError>>(e: E) -> Error {
    Error::new(Kind::Body, Some(e))
}

pub(crate) fn decode<E: Into<BoxError>>(e: E) -> Error {
    Error::new(Kind::Decode, Some(e))
}

pub(crate) fn request<E: Into<BoxError>>(e: E) -> Error {
    Error::new(Kind::Request, Some(e))
}

pub(crate) fn dns<E: Into<BoxError>>(e: E) -> BoxError {
    Box::new(DnsError { inner: e.into() })
}

View on GitHub (pinned to 17e9bcb51c)

Solutions

Print the wrapped source: `if let Some(s) = e.source() { eprintln!("{s}"); }` — it carries the real cause (parse error, bad cert, etc.).
If from `.get(str)`, parse and validate the URL first with `url::Url::parse`.
If from `ClientBuilder::build()`, isolate which TLS/identity/proxy call introduced the failure by building incrementally.
Check error.is_builder() before assuming a network failure.

Example fix

// before
let client = Client::builder()
    .identity(identity)?
    .build()?; // 'builder error' if identity/pw mismatch

// after
match Client::builder().identity(identity).build() {
    Ok(c) => c,
    Err(e) => {
        eprintln!("build failed: {}", e.source().map(|s| s.to_string()).unwrap_or_default());
        Client::new()
    }
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate URLs before they reach the client.
let parsed = url::Url::parse(&raw).map_err(|e| anyhow!("bad url: {e}"))?;
if !matches!(parsed.scheme(), "http" | "https") {
    return Err(anyhow!("scheme not allowed"));
}

Type guard

fn is_builder_error(e: &reqwest::Error) -> bool { e.is_builder() }

Try / catch

let client = match Client::builder().identity(id).build() {
    Ok(c) => c,
    Err(e) if e.is_builder() => {
        log::error!("build failed: {}", e.source().map(|s| s.to_string()).unwrap_or_default());
        Client::new()
    }
    Err(e) => return Err(e.into()),
};

Prevention

Parse and validate URLs at the system boundary, not deep in call sites.
Build Client config incrementally to localize which setting fails.
Always inspect e.source() on builder errors.

When it happens

Trigger: `reqwest::get("not a url")` or any `.get(str)` where the string fails `Url::parse`; `ClientBuilder::build()` failing on bad `add_root_certificate`, `identity`, `tls_built_in_root_certs`, min/max TLS version mismatch, or proxy URL parse error; a redirect `Location` header that isn't a valid URL.

Common situations: Typo'd URL, missing scheme (`example.com` instead of `https://example.com`), loading a `.pfx` identity that doesn't match its password, conflicting TLS settings, or a proxy env var with garbage.

Related errors

AI-assisted analysis of seanmonstar/reqwest@17e9bcb51c (2026-08-06). Data as JSON: /data/errors/aefff98a40be6b23.json. Report an issue: GitHub.