pallets/flask · error · click.BadParameter

Using "--cert" requires Python to be compiled with SSL suppo

Error message

Using "--cert" requires Python to be compiled with SSL support.

What it means

A click.BadParameter raised by `CertParamType.convert` when `--cert` is used but `import ssl` fails. The `ssl` module is part of the standard library only when the Python interpreter was built against OpenSSL headers; without it Flask's dev server cannot serve HTTPS at all, so any `--cert` value is rejected up front.

Source

Thrown at src/flask/cli.py:797

class CertParamType(click.ParamType):  # type: ignore[type-arg]
    """Click option type for the ``--cert`` option. Allows either an
    existing file, the string ``'adhoc'``, or an import for a
    :class:`~ssl.SSLContext` object.
    """

    name = "path"

    def __init__(self) -> None:
        self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True)

    def convert(
        self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
    ) -> t.Any:
        try:
            import ssl
        except ImportError:
            raise click.BadParameter(
                'Using "--cert" requires Python to be compiled with SSL support.',
                ctx,
                param,
            ) from None

        try:
            return self.path_type(value, param, ctx)
        except click.BadParameter:
            value = click.STRING(value, param, ctx).lower()  # type: ignore[union-attr]

            if value == "adhoc":
                try:
                    import cryptography  # noqa: F401
                except ImportError:
                    raise click.BadParameter(
                        "Using ad-hoc certificates requires the cryptography library.",
                        ctx,
                        param,

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Verify the interpreter: `python -c 'import ssl'` — if it fails, install OpenSSL dev headers (`apt install libssl-dev` / `dnf install openssl-devel`) and rebuild/reinstall Python (e.g. `pyenv install 3.12`).
Switch to a distribution Python or official docker image that ships with ssl support.
If you can't fix the interpreter, run without --cert and terminate TLS in a reverse proxy (nginx/caddy) in front of the app.

Example fix

# before
flask run --cert=adhoc   # Python built without ssl
# after
sudo apt install libssl-dev && pyenv install 3.12 && pyenv local 3.12
flask run --cert=adhoc

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("ssl") is None:
    raise SystemExit("This Python lacks SSL support; use a Python built with OpenSSL or terminate TLS at a reverse proxy")

Type guard

def python_has_ssl():
    try:
        import ssl  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    ctx = _validate_cert_key(ctx, param, value)
except click.BadParameter as e:
    print(f"--cert unusable: {e.message}", file=sys.stderr)
    sys.exit(2)

Prevention

Use an official/distribution Python build — SSL-less interpreters usually come from source builds missing OpenSSL headers
Check once per environment with python -c "import ssl" before relying on --cert
In production terminate TLS at nginx/Caddy instead of the dev server's --cert

When it happens

Trigger: `flask run --cert=cert.pem` (or `--cert=adhoc`) under a Python interpreter compiled without SSL support — typically a from-source build where libssl-dev/openssl-devel headers were absent at compile time.

Common situations: Custom-compiled Python (pyenv, `make install`) on a machine missing OpenSSL dev headers; minimal container base images or embedded/stripped Python distributions; broken conda/OpenSSL linkage after system upgrades.

Related errors

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/dd1b1082fc630df6.json. Report an issue: GitHub ↗.