vllm-project/vllm · error

--ssl-ca-certs is required when --ssl-cert-reqs is {} (clien

Error message

--ssl-ca-certs is required when --ssl-cert-reqs is {} (client certificate verification)

What it means

Thrown by TlsConfig::validate() when --ssl-cert-reqs is 1 (optional) or 2 (required) but --ssl-ca-certs is not set. Client certificate verification needs a CA bundle to verify against, so the configuration is structurally incomplete. The message includes the cert_reqs value that triggered it.

Source

Thrown at rust/src/server/src/config.rs:148

impl TlsConfig {
    /// Structurally validate the TLS arguments; the cert/key material is parsed
    /// later, when the OpenSSL context is built.
    pub fn validate(&self) -> Result<()> {
        if self.cert_file.is_none() {
            bail!(
                "--ssl-certfile is required to enable TLS; \
                 --ssl-keyfile/--ssl-ca-certs/--ssl-cert-reqs/--ssl-ciphers \
                 cannot be used without it"
            );
        }
        if !matches!(self.cert_reqs, 0..=2) {
            bail!(
                "--ssl-cert-reqs must be 0 (none), 1 (optional), or 2 (required), got {}",
                self.cert_reqs
            );
        }
        if self.cert_reqs != 0 && self.ca_certs.is_none() {
            bail!(
                "--ssl-ca-certs is required when --ssl-cert-reqs is {} \
                 (client certificate verification)",
                self.cert_reqs
            );
        }
        Ok(())
    }
}

/// Normalized runtime configuration for the minimal OpenAI-compatible server.
#[derive(Educe, Clone, PartialEq, Eq, Serialize)]
#[educe(Debug)]
pub struct Config {
    /// Frontend-to-engine transport setup.
    pub transport_mode: TransportMode,
    /// Deployment-wide data-parallel size retained by the frontend.
    pub data_parallel_size: usize,
    /// Requested frontend-side coordinator behavior.

View on GitHub (pinned to c794754062)

Solutions

1. Provide the CA bundle used to verify client certificates: --ssl-ca-certs ca.pem.
2. If client certificate verification was not intended, set --ssl-cert-reqs 0.
3. Confirm the CA file contains PEM-formatted CA certificates the clients' certs chain to.

Example fix

# before
--ssl-certfile server.pem --ssl-keyfile server.key --ssl-cert-reqs 2

# after
--ssl-certfile server.pem --ssl-keyfile server.key --ssl-cert-reqs 2 --ssl-ca-certs client-ca.pem

fn client_verify_complete(cert_reqs: i32, ca: &Option<PathBuf>) -> bool {
    cert_reqs == 0 || ca.is_some()
}

fn mtls_config_is_valid(tls: &TlsConfig) -> bool {
    tls.cert_reqs == 0 || tls.ca_certs.is_some()
}

When it happens

Trigger: Enabling mTLS with --ssl-certfile server.pem --ssl-cert-reqs 2 while omitting --ssl-ca-certs. Runs after the cert-reqs range check, so it fires only for cert_reqs values 1 or 2 with a valid cert file present.

Common situations: Hardening a deployment for client-certificate auth and forgetting the trust bundle; porting an nginx/grpc mutual-TLS config where the CA was implicit; CI test harness enabling cert-reqs to check the error path.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• --ssl-certfile is required to enable TLS; --ssl-keyfile/--ss
• --ssl-cert-reqs must be 0 (none), 1 (optional), or 2 (requir
• invalid --allowed-methods value {method:?}: {e}
• invalid --allowed-headers value {header:?}: {e}
• max_logprobs must be non-negative or -1, got {}

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/4ec1eac00a7b0562. Report an issue: GitHub.