reflex-dev/reflex · error · Exception

project search failed: {ex_details}

Error message

project search failed: {ex_details}

What it means

Raised by search_project() when the GET /api/v1/project/search request returns a non-2xx status other than 404 (404 means 'no such project' and returns None). The message embeds the server's JSON 'detail' field, so the exact text comes from the hosting service (e.g. validation errors, 401/403 auth failures, 5xx outages). Note it raises a bare Exception, not a library-specific type.

Source

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

    import httpx

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

    response = httpx.get(
        urljoin(constants.Hosting.HOSTING_SERVICE, "/api/v1/project/search"),
        params={"project_name": project_name},
        headers=authorization_header(client.token),
        timeout=constants.Hosting.TIMEOUT,
    )

    try:
        response.raise_for_status()
    except httpx.HTTPStatusError as ex:
        if response.status_code == HTTPStatus.NOT_FOUND:
            return None
        ex_details = ex.response.json().get("detail")
        raise Exception(f"project search failed: {ex_details}") from ex

    projects = response.json()

    if len(projects) > 1 and not interactive:
        logger.error(
            f"Multiple projects with the name {project_name!r} found. Please provide a unique name."
        )
        raise click.exceptions.Exit(1)

    if len(projects) > 1 and interactive:
        return interactive_resolve_project_or_app_name_conflicts(
            projects,
            rows=[[f"({i})", x["id"], x["name"]] for i, x in enumerate(projects)],
            headers=["", "Project ID", "Project name"],
            conflict_warn_msg="Found multiple projects with the same name. Select one to continue",
            conflict_ask_msg="Which project would you like to use?",
        )
    if len(projects) == 1:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Re-authenticate (`reflex login`) and retry — expired tokens are the most common cause of a 401 detail
2. Inspect the detail text: it is the server's JSON 'detail' field and states the actual reason (auth, permission, validation)
3. Check the hosting service status / HOSTING_SERVICE URL configuration if detail suggests 5xx or connectivity issues
4. Catch Exception around search_project in scripts (it is a bare Exception) and surface the detail to the user

try:
    projects = search_project(client, project_name)
except Exception as ex:  # library raises bare Exception
    if "401" in str(ex) or "Unauthorized" in str(ex):
        client = authenticate()
        projects = search_project(client, project_name)
    else:
        raise

When it happens

Trigger: Any HTTP error from the project search endpoint except 404: expired/revoked token (401), no access to the named project (403), malformed project_name the backend rejects (422), or hosting service downtime (5xx). Reachable through list_apps, deploy, select_project, get_project_roles, get_project_role_permissions, get_project_role_users.

Common situations: Token expired between login and the call; pointing constants.Hosting.HOSTING_SERVICE at a wrong/custom URL; hosting service incident; project name containing characters the API rejects.

Related errors

• detail
• app_id should be a string
• app_name should be a string
• deployment failed: {ex_details}
• bad hostname provided

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