{"record":{"id":"4ec1eac00a7b0562","repo":"vllm-project/vllm","slug":"ssl-ca-certs-is-required-when-ssl-cert-reqs-is","errorCode":null,"errorMessage":"--ssl-ca-certs is required when --ssl-cert-reqs is {} (client certificate verification)","messagePattern":"--ssl-ca-certs is required when --ssl-cert-reqs is (.+?) \\(client certificate verification\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"rust/src/server/src/config.rs","lineNumber":148,"sourceCode":"impl TlsConfig {\n    /// Structurally validate the TLS arguments; the cert/key material is parsed\n    /// later, when the OpenSSL context is built.\n    pub fn validate(&self) -> Result<()> {\n        if self.cert_file.is_none() {\n            bail!(\n                \"--ssl-certfile is required to enable TLS; \\\n                 --ssl-keyfile/--ssl-ca-certs/--ssl-cert-reqs/--ssl-ciphers \\\n                 cannot be used without it\"\n            );\n        }\n        if !matches!(self.cert_reqs, 0..=2) {\n            bail!(\n                \"--ssl-cert-reqs must be 0 (none), 1 (optional), or 2 (required), got {}\",\n                self.cert_reqs\n            );\n        }\n        if self.cert_reqs != 0 && self.ca_certs.is_none() {\n            bail!(\n                \"--ssl-ca-certs is required when --ssl-cert-reqs is {} \\\n                 (client certificate verification)\",\n                self.cert_reqs\n            );\n        }\n        Ok(())\n    }\n}\n\n/// Normalized runtime configuration for the minimal OpenAI-compatible server.\n#[derive(Educe, Clone, PartialEq, Eq, Serialize)]\n#[educe(Debug)]\npub struct Config {\n    /// Frontend-to-engine transport setup.\n    pub transport_mode: TransportMode,\n    /// Deployment-wide data-parallel size retained by the frontend.\n    pub data_parallel_size: usize,\n    /// Requested frontend-side coordinator behavior.","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/rust/src/server/src/config.rs#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide the CA bundle used to verify client certificates: --ssl-ca-certs ca.pem.","If client certificate verification was not intended, set --ssl-cert-reqs 0.","Confirm the CA file contains PEM-formatted CA certificates the clients' certs chain to."],"exampleFix":"# before\n--ssl-certfile server.pem --ssl-keyfile server.key --ssl-cert-reqs 2\n\n# after\n--ssl-certfile server.pem --ssl-keyfile server.key --ssl-cert-reqs 2 --ssl-ca-certs client-ca.pem","handlingStrategy":"validation","validationCode":"fn client_verify_complete(cert_reqs: i32, ca: &Option<PathBuf>) -> bool {\n    cert_reqs == 0 || ca.is_some()\n}","typeGuard":"fn mtls_config_is_valid(tls: &TlsConfig) -> bool {\n    tls.cert_reqs == 0 || tls.ca_certs.is_some()\n}","tryCatchPattern":null,"preventionTips":["Always pair --ssl-cert-reqs 1|2 with --ssl-ca-certs in the same flag block.","Store the mTLS flag trio in a shared template or systemd drop-in.","Verify the CA file exists and is PEM before launch."],"tags":["configuration","tls","mtls","security","rust","vllm","startup"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}