sgl-project/sglang · error · ValueError

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

Error message

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

What it means

ServerArgs validation error raised when --ssl-keyfile is provided without --ssl-certfile. Enabling TLS on the HTTP server requires both halves of the key/certificate pair; a key alone cannot configure SSL.

Source

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

            # Default behavior:
            # - non-PD: round_robin
            # - PD prefill: follow_bootstrap_room
            # - PD decode: round_robin
            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(

View on GitHub (pinned to 0132848349)

Solutions

Add the matching --ssl-certfile server.crt to the command
Verify both files exist and match (openssl x509 -noout -modulus vs openssl rsa -noout -modulus)

Example fix

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

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

Always configure cert and key as an inseparable pair in your deployment manifests
Validate the pair in CI config linting before rollout

When it happens

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

Common situations: Partial TLS configuration copied from a runbook; assuming a default cert path; flag order mangled in generated launch commands.

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/34e5abfa579f3c9e. Report an issue: GitHub.