sgl-project/sglang · error · ValueError

--ssl-certfile requires --ssl-keyfile to be specified as wel

Error message

--ssl-certfile requires --ssl-keyfile to be specified as well.

What it means

ServerArgs validation error raised when --ssl-certfile is provided without --ssl-keyfile. A certificate alone is not enough; the server needs the private key to complete the TLS handshake, so SGLang validates the pair up front.

Source

Thrown at python/sglang/srt/server_args.py:4314

            self._declare(
                "_handle_load_balance_method",
                load_balance_method=(
                    "follow_bootstrap_room"
                    if cfg.disaggregation_mode == "prefill"
                    else "round_robin"
                ),
            )
            return

    def _handle_ssl_validation(self):
        """Ensure SSL arguments are consistent and referenced files exist."""
        cfg = resolving_view(self)
        if cfg.ssl_keyfile and not cfg.ssl_certfile:
            raise ValueError(
                "--ssl-keyfile requires --ssl-certfile to be specified as well."
            )
        if cfg.ssl_certfile and not cfg.ssl_keyfile:
            raise ValueError(
                "--ssl-certfile requires --ssl-keyfile to be specified as well."
            )
        if not cfg.ssl_certfile and not cfg.ssl_keyfile:
            if cfg.ssl_ca_certs:
                raise ValueError(
                    "--ssl-ca-certs has no effect without --ssl-certfile and --ssl-keyfile."
                )
            if cfg.ssl_keyfile_password:
                raise ValueError(
                    "--ssl-keyfile-password has no effect without --ssl-certfile and --ssl-keyfile."
                )
        # Validate files exist early to avoid late failures after model loading.
        if cfg.ssl_keyfile and not os.path.isfile(cfg.ssl_keyfile):
            raise ValueError(
                f"SSL key file not found: '{cfg.ssl_keyfile}'. "
                f"Please check the --ssl-keyfile path."
            )
        if cfg.ssl_certfile and not os.path.isfile(cfg.ssl_certfile):

View on GitHub (pinned to 0132848349)

Solutions

Add the matching --ssl-keyfile server.key to the command
Verify both files exist and the key matches the certificate

Example fix

# before
--ssl-certfile server.crt
# after
--ssl-certfile server.crt --ssl-keyfile server.key

Defensive patterns

Strategy: validation

Validate before calling

import os

def ssl_flags(cert: str | None, key: str | None) -> list[str]:
    if bool(cert) != bool(key):
        raise ValueError("--ssl-certfile and --ssl-keyfile must be provided together")
    return ([] if not cert else ["--ssl-certfile", cert, "ssl-keyfile", key])

Prevention

Treat TLS config as one unit (cert + key + optional ca) toggled by a single enable switch
Never template one of the pair conditionally without the other

When it happens

Trigger: Launching with --ssl-certfile server.crt while omitting --ssl-keyfile.

Common situations: Ops templates that only expose the cert path; cert renewed via automation but key flag dropped; misconfigured Helm values or systemd unit.

Understand the failure class

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

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/10d966773633f3d9. Report an issue: GitHub.