Error handling | SurrealDB

Handle exceptions and feature-support errors raised by the SurrealDB Kotlin SDK.

Networked operations on the SDK throw a SurrealException on failure, or you can use the Result variants to handle failures functionally without exceptions.

Exception hierarchy

All SDK exceptions extend the sealed base SurrealException.

Exception	Raised when
`SurrealTransportException`	The connection fails or drops
`SurrealProtocolException`	A malformed or unexpected protocol message is received
`SurrealRpcException`	The server returns an RPC error (carries `code` and `data`)
`SurrealAuthenticationException`	Authentication fails (a subclass of `SurrealRpcException`)
`SurrealFeatureNotSupportedException`	A feature is unavailable on the current transport

Catching exceptions

Because SurrealException is a sealed class, you can exhaustively branch on it with when.

import com.surrealdb.kotlin.error.SurrealAuthenticationException
import com.surrealdb.kotlin.error.SurrealException
import com.surrealdb.kotlin.error.SurrealRpcException
import com.surrealdb.kotlin.error.SurrealTransportException

try {
    client.signin(buildJsonObject {
        put("user", "root")
        put("pass", "wrong")
    })
} catch (e: SurrealAuthenticationException) {
    println("bad credentials: ${e.message}")
} catch (e: SurrealRpcException) {
    println("server error ${e.code}: ${e.message}")
} catch (e: SurrealTransportException) {
    println("connection problem: ${e.message}")
} catch (e: SurrealException) {
    println("unexpected: ${e.message}")
}

Feature support errors

Calling a feature that the current transport does not support — for example a live query over HTTP — throws SurrealFeatureNotSupportedException. Guard against this with .supports().

import com.surrealdb.kotlin.SurrealFeature

if (client.supports(SurrealFeature.LiveQueries)) {
    val subscription = client.live("person")
}

Using Result variants

Each networked method has a ...Result companion that wraps the outcome in a Result instead of throwing.

client.queryResult("SELECT * FROM person")
    .onSuccess { println("got $it") }
    .onFailure { println("failed: ${it.message}") }

Learn more

Errors reference for every exception type
Features and events for checking transport support
Executing queries for the Result variants