Error handling | Kotlin SDK

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.

The error kinds, wire codes and structured shape behind these are documented once in Errors, which applies to every SDK and protocol.

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