pallets/flask · error · click.BadParameter

Using ad-hoc certificates requires the cryptography library.

Error message

Using ad-hoc certificates requires the cryptography library.

What it means

A click.BadParameter raised by `CertParamType.convert` when `--cert=adhoc` is requested but `import cryptography` fails. Ad-hoc mode asks Werkzeug to generate a temporary self-signed certificate on the fly, which requires the optional `cryptography` package; a file-based `--cert` does not need it.

Source

Thrown at src/flask/cli.py:812

        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,
                    ) from None

                return value

            obj = import_string(value, silent=True)

            if isinstance(obj, ssl.SSLContext):
                return obj

            raise


def _validate_key(ctx: click.Context, param: click.Parameter, value: t.Any) -> t.Any:
    """The ``--key`` option must be specified when ``--cert`` is a file.
    Modifies the ``cert`` param to be a ``(cert, key)`` pair if needed.

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Install the package: `pip install cryptography`, then rerun `flask run --cert=adhoc`.
Alternatively generate a real self-signed cert once and pass files instead: `openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes` then `flask run --cert=cert.pem --key=key.pem`.
For production-like HTTPS, use mkcert or a reverse proxy rather than ad-hoc certificates.

Example fix

# before
flask run --cert=adhoc   # cryptography not installed
# after
pip install cryptography
flask run --cert=adhoc

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("cryptography") is None:
    raise SystemExit("pip install cryptography before using --cert adhoc")

Try / catch

try:
    run_command(cert="adhoc")
except click.BadParameter:
    print("Install 'cryptography' or pass real cert/key files instead of adhoc", file=sys.stderr)
    sys.exit(2)

Prevention

Add cryptography as a dev dependency if the team uses 'flask run --cert adhoc'
Prefer mkcert-generated local certificates over adhoc — stable, browser-trusted, and no extra runtime dependency
Keep adhoc certs strictly for local development; production TLS belongs at the proxy layer

When it happens

Trigger: `flask run --cert=adhoc` in an environment without the cryptography package installed. The check fires only for the literal value `adhoc` (case-insensitive), after the value fails to resolve as an existing file path.

Common situations: Quick local HTTPS testing following tutorial commands without installing extras; slim Docker/CI environments with only core dependencies; cryptography missing wheels on unusual platforms so the install was skipped.

Related errors

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