What causes "bad hostname provided" in reflex-dev/reflex?

Pass a plain subdomain (e.g. `my-app`) or a URL whose subdomain is extractable, like `my-app.reflex.run`

reflex-dev/reflex · error · Exception

bad hostname provided

Error message

bad hostname provided

What it means

Raised by get_hostname when an explicit hostname argument cannot be reduced to a valid subdomain: extract_subdomain returns None, meaning the string has no usable subdomain part. This is a client-side validation failure before the reserve request is sent.

Source

Thrown at packages/reflex-hosting-cli/src/reflex_cli/utils/hosting.py:1491

    Returns:
        dict: The hostname details as a dictionary.

    Raises:
        NotAuthenticatedError: If the token is not valid.
        Exception: If deployment fails or the hostname is invalid.

    """
    import httpx

    if not isinstance(client, AuthenticatedClient):
        raise NotAuthenticatedError("not authenticated")

    data = {"app_id": app_id, "app_name": app_name}
    if hostname:
        clean_hostname = extract_subdomain(hostname)
        if clean_hostname is None:
            raise Exception("bad hostname provided")
        data["hostname"] = clean_hostname
    response = httpx.post(
        urljoin(constants.Hosting.HOSTING_SERVICE, "/api/v1/apps/reserve"),
        headers=authorization_header(client.token),
        json=data,
        timeout=constants.Hosting.TIMEOUT,
    )
    try:
        response.raise_for_status()
    except httpx.HTTPStatusError as ex:
        if ex.response.status_code == 413:
            raise Exception(
                "deployment failed: the deployment payload is too large (over 100MB). "
                "Please reduce the size of your project by removing large files or "
                "adding them to your .gitignore file."
            ) from ex
        try:
            ex_details = ex.response.json().get("detail")

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Pass a plain subdomain (e.g. `my-app`) or a URL whose subdomain is extractable, like `my-app.reflex.run`
Check that the hostname is non-empty and contains at least one label before a dot
Avoid protocol prefixes and paths in the hostname value

Example fix

# before
get_hostname(client, app_id, app_name, hostname="example.com")

# after
get_hostname(client, app_id, app_name, hostname="my-app.reflex.run")

Defensive patterns

Strategy: validation

Validate before calling

from reflex_cli.utils.hosting import extract_subdomain
assert hostname and extract_subdomain(hostname) is not None, "hostname must contain a valid subdomain"

Type guard

def is_valid_hostname(hostname: str) -> bool:
    return bool(hostname) and extract_subdomain(hostname) is not None

Try / catch

try:
    get_hostname(client, app_id, app_name, hostname=hostname)
except Exception as e:
    if "bad hostname" in str(e):
        hostname = None  # fall back to default
        get_hostname(client, app_id, app_name)

Prevention

Pass a plain subdomain like 'my-app' rather than a full domain
Test custom hostnames with extract_subdomain before deploying
Avoid apex domains and URLs with schemes/paths

When it happens

Trigger: Passing a bare domain without a subdomain, an empty string, or a malformed value as the hostname argument to `reflex deploy --hostname` / get_hostname.

Common situations: Users passing a full custom domain they own, a domain with only dots/TLD, or a typo'd hostname; hosting a custom apex domain instead of a subdomain.

Related errors

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/3e01298121dcb120. Report an issue: GitHub.