sgl-project/sglang · error · ValueError

--ssl-ca-certs has no effect without --ssl-certfile and --ss

Error message

--ssl-ca-certs has no effect without --ssl-certfile and --ssl-keyfile.

What it means

ServerArgs validation error raised when --ssl-ca-certs is set but neither --ssl-certfile nor --ssl-keyfile is. CA certs only matter for verifying clients/peers once server TLS is enabled; without the key/cert pair they are inert, so SGLang fails fast to surface the misconfiguration.

Source

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

                    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):
            raise ValueError(
                f"SSL certificate file not found: '{cfg.ssl_certfile}'. "
                f"Please check the --ssl-certfile path."
            )
        if cfg.ssl_ca_certs and not os.path.isfile(cfg.ssl_ca_certs):

View on GitHub (pinned to 0132848349)

Solutions

Enable server TLS: add both --ssl-certfile and --ssl-keyfile alongside --ssl-ca-certs
If TLS is intentionally off, remove --ssl-ca-certs

Example fix

# before
--ssl-ca-certs ca.pem
# after
--ssl-certfile server.crt --ssl-keyfile server.key --ssl-ca-certs ca.pem

Defensive patterns

Strategy: validation

Validate before calling

def ca_certs_allowed(cert: str | None, key: str | None, ca: str | None) -> bool:
    return not ca or bool(cert and key)

Prevention

Only set --ssl-ca-certs in the same config block that enables --ssl-certfile/--ssl-keyfile
Use a single tls_enabled toggle in deployment tooling that derives all four SSL flags

When it happens

Trigger: Launching with --ssl-ca-certs ca.pem and no --ssl-certfile/--ssl-keyfile.

Common situations: Attempting client-CA verification without enabling server TLS; leftover flag after disabling TLS; misunderstanding that ca-certs alone does not turn on HTTPS.

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