# Errors

The exception hierarchy raised by the SurrealDB Kotlin SDK.

The Kotlin SDK raises exceptions that all extend the sealed base class `SurrealException`. Because the hierarchy is sealed, you can branch over it exhaustively with `when`. See [Error handling](/docs/reference/kotlin/concepts/error-handling.md) for usage patterns and the [`Result` variants](/docs/reference/kotlin/concepts/executing-queries.md#result-variants) that avoid exceptions altogether.

**Source:** [surrealdb.kotlin](https://github.com/surrealdb/surrealdb.kotlin)

```kotlin title="Import"
import com.surrealdb.kotlin.error.SurrealException
```

---

## `SurrealException` {#surreal-exception}

The sealed base class of all SDK exceptions. Extends `RuntimeException`.

## `SurrealTransportException` {#transport}

Raised when the underlying connection fails, drops, or cannot be established.

## `SurrealProtocolException` {#protocol}

Raised when a malformed or unexpected message is received from the server.

## `SurrealRpcException` {#rpc}

Raised when the server returns an RPC error.

<table>
    <thead>
        <tr><th>Property</th><th>Type</th><th>Description</th></tr>
    </thead>
    <tbody>
        <tr><td><code>code</code></td><td><code>Int?</code></td><td>The RPC error code.</td></tr>
        <tr><td><code>data</code></td><td><code>JsonElement?</code></td><td>Additional error data from the server.</td></tr>
    </tbody>
</table>

## `SurrealAuthenticationException` {#authentication}

A subclass of [`SurrealRpcException`](#rpc) raised when authentication fails (for example, invalid credentials or an expired token).

## `SurrealFeatureNotSupportedException` {#feature-not-supported}

Raised when a feature is invoked that the current transport does not support - for example a [live query](/docs/reference/kotlin/concepts/live-queries.md) or [transaction](/docs/reference/kotlin/concepts/transactions.md) over HTTP. Extends the base [`SurrealException`](#surreal-exception). Guard against it with [`.supports()`](/docs/reference/kotlin/api/core/surreal-client.md#supports).

```kotlin title="Example"
import com.surrealdb.kotlin.error.SurrealAuthenticationException
import com.surrealdb.kotlin.error.SurrealException

try {
    client.signin(buildJsonObject { put("user", "root"); put("pass", "wrong") })
} catch (e: SurrealAuthenticationException) {
    println("authentication failed: ${e.message}")
} catch (e: SurrealException) {
    println("error: ${e.message}")
}
```

## Learn more

- [Error handling](/docs/reference/kotlin/concepts/error-handling.md)
- [Features and events](/docs/reference/kotlin/api/features.md)