sgl-project/sglang · error · ValueError

--ssl-keyfile-password has no effect without --ssl-certfile

Error message

--ssl-keyfile-password has no effect without --ssl-certfile and --ssl-keyfile.

What it means

ServerArgs validation error raised when --ssl-keyfile-password is set but neither --ssl-certfile nor --ssl-keyfile is. The password decrypts the (encrypted) private key, so it is meaningless without the key file; SGLang fails fast to catch the incomplete TLS setup.

Source

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

    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):
            raise ValueError(
                f"SSL CA certificates file not found: '{cfg.ssl_ca_certs}'. "
                f"Please check the --ssl-ca-certs path."
            )

View on GitHub (pinned to 0132848349)

Solutions

Add --ssl-keyfile (and --ssl-certfile) to actually enable TLS
If not using TLS, remove --ssl-keyfile-password from the command/secret store

Example fix

# before
--ssl-keyfile-password $SSL_PASS
# after
--ssl-certfile server.crt --ssl-keyfile server.enc.key --ssl-keyfile-password $SSL_PASS

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Inject --ssl-keyfile-password only through the same secret/template path that sets cert and key
Audit secret stores for orphaned TLS password entries after config changes

When it happens

Trigger: Launching with --ssl-keyfile-password **** while omitting both --ssl-keyfile and --ssl-certfile.

Common situations: Secrets injected via environment automation while the file flags were dropped; leftover config after moving to unencrypted keys; templated launch commands with conditional flags evaluated inconsistently.

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