Document rustls-no-provider initialization requirement

[clouatre]

---

Problem

Using rustls-no-provider causes a runtime panic if the crypto provider isn't manually initialized:

thread 'main' panicked at reqwest-0.13.1/src/async_impl/client.rs:2450:5:
No provider set

This requirement is not documented in the README or migration guide.

Reproduction

reqwest = { version = "0.13", features = ["rustls-no-provider"] }
rustls = { version = "0.23", features = ["ring"] }

#[tokio::main]
async fn main() {
    let client = reqwest::Client::new(); // panics here
}

Current Workaround

Initialize the provider before creating clients:

#[tokio::main]
async fn main() {
    rustls::crypto::ring::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");
    
    let client = reqwest::Client::new(); // now works
}

Suggested Solutions

Option 1: Better Error Message (Easy)

Change the panic message to include initialization instructions:

No rustls crypto provider set. When using rustls-no-provider, you must call:
  rustls::crypto::ring::default_provider().install_default()
before creating any reqwest clients.

Option 2: Convenience Features (Medium)

Add features that handle initialization automatically:

• rustls-ring - uses ring provider with auto-init
• rustls-aws-lc - uses aws-lc-rs provider with auto-init

This would make migration from 0.12 smoother.

Option 3: Documentation (Easy)

Add to README under TLS backends section:

### Using `rustls-no-provider`

To use a specific crypto provider (e.g., `ring` instead of default `aws-lc-rs`):

```toml
reqwest = { version = "0.13", default-features = false, features = ["rustls-no-provider"] }
rustls = { version = "0.23", features = ["ring"] }
```

**Required:** Initialize the provider before creating any clients:

```rust
rustls::crypto::ring::default_provider()
    .install_default()
    .expect("Failed to install rustls crypto provider");
```

⚠️ Forgetting this will cause a runtime panic.

Context

• reqwest 0.12 with rustls-tls worked without manual initialization
• 0.13.0 released Dec 30, 2025 (yesterday)
• Affects users avoiding aws-lc-rs for binary size or build simplicity

Related

• Use rustls default provider unless specified #2423 - Use rustls default provider unless specified
• Recommendations for libraries using reqwest #2871 - Recommendations for libraries using reqwest

[seanmonstar]

Good point, I think the two suggestions we should do:

1. Improve the panic message to better guide people.
2. Add a section in the reqwest::tls module documentation about rustls-no-provider.

[clouatre]

Thanks for the quick response, Sean! Really appreciate the responsiveness.

Options 1 and 3 will definitely help. For context on Option 2's impact:

We attempted migrating from 0.12 to 0.13 with rustls-no-provider to avoid
aws-lc-rs (build deps, binary size). The migration required:

• Manual rustls::crypto::ring::default_provider().install_default() in main()
• Thread-safe Once initialization in every test file
• ~15 lines of boilerplate total
• Runtime panic risk if initialization is forgotten anywhere

We ultimately abandoned the migration. The complexity wasn't worth ~100KB savings.

With a convenience feature like rustls-ring (parallel to how rustls implies
aws-lc-rs), the migration would have been a one-line Cargo.toml change:

# From
reqwest = { version = "0.12", features = ["json", "rustls-tls"] }

# To  
reqwest = { version = "0.13", features = ["json", "rustls-ring"] }

Implementation-wise, this could mirror the existing pattern:

# Existing
rustls = ["__rustls-aws-lc-rs", "dep:rustls-platform-verifier", "__rustls"]

# New
rustls-ring = ["__rustls-ring", "dep:rustls-platform-verifier", "__rustls"]

Happy to submit a PR if there's interest. Either way, thanks for reqwest. It's
been rock solid for years.

[seanmonstar]

I do empathize with the desire for suggestion 2. However, we used to have those, and with v0.13, we purposefully removed them because the complexity within reqwest was significant, and it was also confusing for users if different crates enable different features to configure rustls. While this shifts some of the work in the simpler case on to users, the hope is that it's less complexity overall.

[JosiahParry]

We're encountering this as well for our work using the kube crate. It would be less of a surprise if it wasn't just a minor version bump!

Anywho! If anyone else is encountering this with kube the fix for me was to add aws-lc-rs feature

[tustvold]

So I am trying to work the reqwest 0.13 upgrade into object_store and running into this as a non-trivial snag.

As far as I can tell this change means downstream libraries that perform cryptography in addition to rustls (e.g. token signing) must do one of the following:

• Switch to using aws-lc-rs instead of ring
• Bundle two cryptography libraries
• Force users to do manual shenanigans to setup ring

This is especially unfortunate for crates that support platforms aws-lc-rs doesn't support, e.g. WASM.

Fortunately we had a concurrent effort to make cryptography pluggable (actually to support openssl) and so I've bundled the reqwest 0.13 update into this, but I wonder if there is some alternative to this?

[erka]

This really feels like a lose-lose situation. aws-lc-rs is built with iOS 18.5, so it can’t be used on older versions, switching to ring is a pretty painful migration. Debian Bullseye seems to be falling apart with any provider while it works with reqwest 0.12.9 out of the box.

[justsmth]

aws-lc-rs is built with iOS 18.5, so it can’t be used on older versions, ...

Hello @erka! Sorry, I didn't realize that the aws-lc-rs build setup prevented building for older iOS versions. If you would like to submit an issue to the aws-lc-rs repo with information about the build/runtime failure you see, we will look into it.