What causes "When "--cert" is "adhoc", "--key" is not used." in pallets/flask?

Remove the `--key` option: `flask run --cert adhoc`.

pallets/flask · error · click.BadParameter

When "--cert" is "adhoc", "--key" is not used.

Error message

When "--cert" is "adhoc", "--key" is not used.

What it means

Raised by Flask's CLI (`_validate_key` in src/flask/cli.py) as a click.BadParameter when `flask run --cert adhoc --key <file>` is used. Adhoc mode generates a self-signed certificate and key on the fly via pyOpenSSL, so a user-supplied private key is contradictory and Flask fails fast rather than silently ignoring it.

Source

Thrown at src/flask/cli.py:844


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.
    """
    cert = ctx.params.get("cert")
    is_adhoc = cert == "adhoc"

    try:
        import ssl
    except ImportError:
        is_context = False
    else:
        is_context = isinstance(cert, ssl.SSLContext)

    if value is not None:
        if is_adhoc:
            raise click.BadParameter(
                'When "--cert" is "adhoc", "--key" is not used.', ctx, param
            )

        if is_context:
            raise click.BadParameter(
                'When "--cert" is an SSLContext object, "--key" is not used.',
                ctx,
                param,
            )

        if not cert:
            raise click.BadParameter('"--cert" must also be specified.', ctx, param)

        ctx.params["cert"] = cert, value

    else:
        if cert and not (is_adhoc or is_context):
            raise click.BadParameter('Required when using "--cert".', ctx, param)

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Remove the `--key` option: `flask run --cert adhoc`.
If you actually want to use your own cert/key pair, replace `adhoc` with the certificate file path: `flask run --cert cert.pem --key key.pem`.
Ensure pyOpenSSL is installed for adhoc mode (`pip install pyopenssl`).

Example fix

# before
flask run --cert adhoc --key key.pem
# after
flask run --cert adhoc

Defensive patterns

Strategy: validation

Validate before calling

# before invoking `flask run`
if cert == "adhoc" and key is not None:
    raise SystemExit("Do not pass --key when --cert=adhoc")

Prevention

Treat --cert adhoc as a complete TLS spec; never pair it with --key
In launch scripts, build CLI args from a single tls config object so cert/key combinations are validated in one place
Use ssl_context='adhoc' in app.run() instead of mixing CLI flags when scripting

When it happens

Trigger: Running `flask run --cert adhoc --key path/to/key.pem`. The `--key` callback checks `ctx.params.get('cert') == 'adhoc'` and rejects any non-None key value.

Common situations: Copying an HTTPS run command that used real cert files and swapping in `adhoc` for quick local TLS while forgetting to delete `--key`; shell scripts or Makefiles that always append `--key` regardless of cert mode.

Related errors

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