pola-rs/polars · error · ValueError

a non-HTTPS workspace_url was given

Error message

a non-HTTPS workspace_url was given ({workspace_url}). To allow non-HTTPS URLs, pass require_https=False.

What it means

The Unity Catalog client raises ValueError when a workspace_url does not start with `https://` while HTTPS enforcement is on (require_https=True by default). This protects bearer tokens from being sent over plaintext connections. Callers can explicitly opt out with require_https=False, but that is discouraged for anything but local testing.

Solutions

1. Use an https:// workspace URL: workspace_url="https://dbc-xxxx.cloud.databricks.com"
2. If intentionally testing against a local non-TLS server, pass require_https=False to the constructor
3. Add the scheme if it is missing: prefix the host with https://

Example fix

// before
client = CatalogClient(workspace_url="http://localhost:8080", bearer_token="t")
// after
client = CatalogClient(workspace_url="https://dbc-xxxx.cloud.databricks.com", bearer_token=tOKEN)
# or, local dev only:
client = CatalogClient(workspace_url="http://localhost:8080", bearer_token="t", require_https=False)

if not workspace_url.startswith("https://") and require_https:
    raise ValueError(f"workspace_url must use https://, got {workspace_url!r}")

def is_https_url(url: str) -> bool:
    return url.startswith("https://")

try:
    client = CatalogClient(workspace_url=url, bearer_token=tok)
except ValueError as e:
    if "non-HTTPS workspace_url" in str(e):
        client = CatalogClient(workspace_url=url, bearer_token=tok, require_https=False)  # dev only
    else:
        raise

When it happens

Trigger: Constructing `CatalogClient(...)` / Unity Catalog client with e.g. workspace_url="http://host:8080" or "localhost:8080" while require_https is left at its default True.

Common situations: Pointing at a local Databricks emulator or dev server over http; forgetting the https:// scheme entirely; pasting an internal hostname without a scheme.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• cannot apply delta_table_options for table of type
• cannot apply delta_table_version for table of type
• could not get Databricks token: databricks-sdk is not…
• write_table: table format of
• accessing ` ` from the top-level `polars` module was…

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/4ea4f511a4b7f44a. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/catalog/unity/client.py:91

            URL of the workspace, or alternatively the URL of the Unity catalog
            API endpoint.
        bearer_token
            Bearer token to authenticate with. This can also be set to:

            * "auto": Automatically retrieve bearer tokens from the environment.
            * "databricks-sdk": Use the Databricks SDK to retrieve and use the
              bearer token from the environment.
        require_https
            Require the `workspace_url` to use HTTPS.
        """
        issue_unstable_warning("`Catalog` functionality is considered unstable.")

        if require_https and not workspace_url.startswith("https://"):
            msg = (
                f"a non-HTTPS workspace_url was given ({workspace_url}). To "
                "allow non-HTTPS URLs, pass require_https=False."
            )
            raise ValueError(msg)

        if bearer_token == "databricks-sdk" or (
            bearer_token == "auto"
            # For security, in "auto" mode, only retrieve/use the token if:
            # * We are running inside a Databricks environment
            # * The `workspace_url` is pointing to Databricks and uses HTTPS
            and "DATABRICKS_RUNTIME_VERSION" in os.environ
            and workspace_url.startswith("https://")
            and (
                workspace_url.removeprefix("https://")
                .split("/", 1)[0]
                .endswith(".cloud.databricks.com")
            )
        ):
            bearer_token = self._get_databricks_token()

        if bearer_token == "auto":
            bearer_token = None

View on GitHub (pinned to fe841f959e)