sgl-project/sglang · error · ValueError

--enable-ssl-refresh requires --ssl-certfile and --ssl-keyfi

Error message

--enable-ssl-refresh requires --ssl-certfile and --ssl-keyfile to be specified.

What it means

--enable-ssl-refresh enables hot-reloading of SSL certificates, which requires both a certificate and its private key to be configured. SGLang raises this error at argument validation when either --ssl-certfile or --ssl-keyfile is missing.

Source

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

                )
        # 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):
            raise ValueError(
                f"SSL CA certificates file not found: '{cfg.ssl_ca_certs}'. "
                f"Please check the --ssl-ca-certs path."
            )
        if cfg.enable_ssl_refresh and not (cfg.ssl_certfile and cfg.ssl_keyfile):
            raise ValueError(
                "--enable-ssl-refresh requires --ssl-certfile and --ssl-keyfile "
                "to be specified."
            )

        if cfg.enable_http2:
            if not 0 < cfg.http2_max_concurrent_streams < 2**32:
                raise ValueError(
                    "--http2-max-concurrent-streams must be between 1 and "
                    "4294967295."
                )

            try:
                import granian  # noqa: F401
            except ImportError:
                raise ValueError(
                    "--enable-http2 requires the 'granian' package. "
                    'Install it with: pip install "sglang[http2]"'
                )

View on GitHub (pinned to 0132848349)

Solutions

Add --ssl-certfile /path/to/cert.pem and --ssl-keyfile /path/to/key.pem alongside --enable-ssl-refresh
Verify both files exist and are readable by the server process
If you do not need hot-reload, remove --enable-ssl-refresh

Example fix

# before
python -m sglang.launch_server --enable-ssl-refresh
# after
python -m sglang.launch_server --enable-ssl-refresh --ssl-certfile /etc/ssl/cert.pem --ssl-keyfile /etc/ssl/key.pem

Defensive patterns

Strategy: validation

Validate before calling

if args.enable_ssl_refresh and not (args.ssl_certfile and args.ssl_keyfile):
    raise SystemExit('--enable-ssl-refresh requires --ssl-certfile and --ssl-keyfile')

Prevention

Treat TLS flags as one unit in config templates
Fail fast in wrapper scripts before invoking the server

When it happens

Trigger: Passing --enable-ssl-refresh without also passing both --ssl-certfile and --ssl-keyfile. Checked in _handle_ssl_validation during startup.

Common situations: Copy-pasted TLS config from another service that only set CA certs; assumed the refresh flag works with defaults; enabled rotation support but forgot the key file argument.

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