pola-rs/polars · error · RuntimeError

{response["result"]}

Error message

{response["result"]}

What it means

`ALTS cursor proxies` (used by the `alts` database adapter in `pl.read_database`) expect each async query result envelope to have `status == "OK"`. `_unpack_result_async` raises `RuntimeError(response["result"])` when the remote ALTS/service reports a non-OK status, surfacing the server-provided error string directly to the caller.

Solutions

1. Read the RuntimeError message — it is the server's `result` field — and fix the underlying query or permission it reports.
2. Validate/limit the SQL query before executing (correct table/column names, syntax).
3. Re-authenticate or refresh credentials for the ALTS connection.
4. Retry with backoff if the status reflects a transient service issue, and check service health.

Example fix

// before
cursor.execute("SELCT * FROM t")  # typo, server returns non-OK status
rows = await cursor.fetchall()  # RuntimeError: parse error...
// after
cursor.execute("SELECT * FROM t")
rows = await cursor.fetchall()

try:
    rows = await cursor.fetchall()
except RuntimeError as e:
    log.error("ALTS query failed: %s", e)
    # inspect e.args for the server-provided reason; fix query/creds or retry

When it happens

Trigger: Calling `fetchall()` on an async ALTS cursor proxy where the first response dict has `status != "OK"` — e.g. a failed SQL query, auth failure, or server-side error returned in the `result` field.

Common situations: Broken or invalid SQL sent through the ALTS endpoint; expired credentials or insufficient permissions on the remote service; the ALTS service returning an error payload that polars unwraps verbatim; network/service outages producing error envelopes.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• Cannot set `iter_batches` for
• Cannot set `iter_batches` without also setting a non-zero…
• `collect_all_async` is not supported by
• `collect_async` is not supported by
• engine must be one of

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

Appendix: source

Thrown at py-polars/src/polars/io/database/_cursor_proxies.py:99

    """Cursor proxy for both SurrealDB and AsyncSurrealDB connections."""

    _cached_result: list[dict[str, Any]] | None = None

    def __init__(self, client: Any) -> None:
        surrealdb = import_optional("surrealdb")
        self.is_async = isinstance(client, surrealdb.AsyncSurrealDB)
        self.execute_options: dict[str, Any] = {}
        self.client = client
        self.query: str = None  # type: ignore[assignment]

    @staticmethod
    async def _unpack_result_async(
        result: Coroutine[Any, Any, list[dict[str, Any]]],
    ) -> Coroutine[Any, Any, list[dict[str, Any]]]:
        """Unpack the async query result."""
        response = (await result)[0]
        if response["status"] != "OK":
            raise RuntimeError(response["result"])
        return response["result"]

    @staticmethod
    def _unpack_result(
        result: list[dict[str, Any]],
    ) -> list[dict[str, Any]]:
        """Unpack the query result."""
        response = result[0]
        if response["status"] != "OK":
            raise RuntimeError(response["result"])
        return response["result"]

    def close(self) -> None:
        """Close the cursor."""
        # no-op; never close a user's Surreal session

    def execute(self, query: str, **execute_options: Any) -> Self:
        """Execute a query (n/a: just store query for the fetch* methods)."""

View on GitHub (pinned to fe841f959e)