{"record":{"id":"1e0b70895fb6c560","repo":"pola-rs/polars","slug":"result","errorCode":null,"errorMessage":"{result}","messagePattern":"\\{result\\}","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/database/_cursor_proxies.py","lineNumber":97,"sourceCode":"    \"\"\"Cursor proxy for both SurrealDB and AsyncSurrealDB connections.\"\"\"\n\n    _cached_result: list[dict[str, Any]] | None = None\n\n    def __init__(self, client: Any) -> None:\n        surrealdb = import_optional(\"surrealdb\")\n        self.is_async = isinstance(client, surrealdb.AsyncSurrealDB)\n        self.execute_options: dict[str, Any] = {}\n        self.client = client\n        self.query: str = None  # type: ignore[assignment]\n\n    @staticmethod\n    async def _unpack_result_async(\n        result: Coroutine[Any, Any, list[dict[str, Any]]],\n    ) -> Coroutine[Any, Any, list[dict[str, Any]]]:\n        \"\"\"Unpack the async query result.\"\"\"\n        response = (await result)[0]\n        if response[\"status\"] != \"OK\":\n            raise RuntimeError(response[\"result\"])\n        return response[\"result\"]\n\n    @staticmethod\n    def _unpack_result(\n        result: list[dict[str, Any]],\n    ) -> list[dict[str, Any]]:\n        \"\"\"Unpack the query result.\"\"\"\n        response = result[0]\n        if response[\"status\"] != \"OK\":\n            raise RuntimeError(response[\"result\"])\n        return response[\"result\"]\n\n    def close(self) -> None:\n        \"\"\"Close the cursor.\"\"\"\n        # no-op; never close a user's Surreal session\n\n    def execute(self, query: str, **execute_options: Any) -> Self:\n        \"\"\"Execute a query (n/a: just store query for the fetch* methods).\"\"\"","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/database/_cursor_proxies.py#L79-L115","documentation":"SurrealDBCursorProxy._unpack_result_async inspects the first response envelope of a SurrealDB query; if its 'status' field is anything other than 'OK' (e.g. 'ERR'), the server-side failure payload in response['result'] is re-raised as a RuntimeError. So the message text you see is SurrealDB's own error detail (syntax error, missing namespace/database, permissions), not polars wording. This is the async path used when read_database receives a surrealdb.SurrealDB (async) client.","triggerScenarios":"pl.read_database(query='SELECT * FROM missing_table', connection=async_surreal_client) after client.connect(); invalid SurrealQL; querying before USE NS/DB or connect(); insufficient record-level permissions.","commonSituations":"Async FastAPI/asyncio services reading from SurrealDB; forgetting await client.use(namespace, database); typos in table names; version drift between the surrealdb python driver and server changing response envelopes.","solutions":["Run the same query in the SurrealDB shell / Studio to see the full server error and fix the query","Ensure the connection is established and a namespace + database are selected before read_database (await client.connect(); await client.use('ns', 'db'))","Wrap the read in try/except RuntimeError and surface err.args[0] for logging, since the payload carries the actionable server message"],"exampleFix":"# before\nawait client.connect()\ndf = pl.read_database('SELECT * FROM orders', connection=client)\n\n# after\nawait client.connect()\nawait client.use('prod', 'app')\ndf = pl.read_database('SELECT * FROM orders', connection=client)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_database(query, connection=async_client)\nexcept RuntimeError as err:\n    detail = err.args[0] if err.args else ''\n    # SurrealDB payloads arrive here: parse/handle known cases\n    if 'was not found' in str(detail):\n        raise KeyError(f'table missing: {detail}') from err\n    raise","preventionTips":["Always connect() and use(namespace, database) before handing the client to read_database","Validate SurrealQL by running it once in surreal CLI during development","Treat RuntimeError from this path as a server message: log err.args[0] verbatim for debugging"],"tags":["polars","database","surrealdb","async","runtimeerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}