# Errors

The Go SDK provides structured error types and sentinel errors for handling SurrealDB failures.

The Go SDK uses Go's standard `error` interface with typed errors that can be inspected using `errors.As` and `errors.Is`. Errors fall into three categories: structured server errors, query-level errors, and sentinel errors for common failure conditions.

**Packages:**
- `github.com/surrealdb/surrealdb.go` (type aliases)
- `github.com/surrealdb/surrealdb.go/pkg/connection` (definitions)
- `github.com/surrealdb/surrealdb.go/pkg/constants` (sentinels)

---

## Error types

### `ServerError` {#servererror}

A structured error returned by SurrealDB v3. Contains a `Kind`, `Message`, `Details`, and an optional `Cause` chain. Use `errors.As` to extract it from any error returned by the SDK.

```go
type ServerError struct {
    Code    int
    Message string
    Kind    string
    Details any
    Cause   *ServerError
}
```

**Methods:**

- `.Error()` - returns the message, joining the cause chain with `": "`
- `.Unwrap()` - returns the `Cause`, enabling `errors.Unwrap()` traversal
- `.Is(target)` - returns `true` if `target` is a `ServerError`
- `.As(target)` - populates `target` if it is `*ServerError` or `**ServerError`

**Available as:** `surrealdb.ServerError` (type alias)

#### Examples

```go
import "errors"

_, err := surrealdb.Select[Person](ctx, db, models.NewRecordID("persons", "missing"))
if err != nil {
    var se *surrealdb.ServerError
    if errors.As(err, &se) {
        fmt.Println("Kind:", se.Kind)
        fmt.Println("Message:", se.Message)
        if se.Details != nil {
            fmt.Println("Details:", se.Details)
        }
    }
}
```

### `QueryError` {#queryerror}

Represents a per-statement error within a query result. Returned in the `Error` field of [`QueryResult`](/docs/reference/golang/api/types.md#queryresult) when an individual statement fails.

```go
type QueryError struct {
    Message string
}
```

**Methods:**

- `.Error()` - returns the error message
- `.Is(target)` - returns `true` if `target` is a `*QueryError`

#### Examples

```go
results, err := surrealdb.Query[[]any](ctx, db, "INVALID SQL", nil)

if errors.Is(err, &surrealdb.QueryError{}) {
    fmt.Println("Query contained errors")
}

for _, qr := range *results {
    if qr.Error != nil {
        fmt.Println("Statement error:", qr.Error.Message)
    }
}
```

### `RPCError` {#rpcerror}

An RPC level error with `Code`, `Message`, and `Description` fields. On SurrealDB v3, `ServerError` is preferred as it provides richer information.

**Available as:** `surrealdb.RPCError` (type alias, deprecated in favour of `ServerError`)

---

## Sentinel errors

These are defined in `github.com/surrealdb/surrealdb.go/pkg/constants`:

| Error | Value | Description |
|---|---|---|
| `ErrSessionsNotSupported` | `"sessions require WebSocket connection"` | Returned when calling `.Attach()` on a non-WebSocket connection |
| `ErrTransactionsNotSupported` | `"interactive transactions require WebSocket connection"` | Returned when calling `.Begin()` on a non-WebSocket connection |
| `ErrSessionClosed` | `"session already detached"` | Returned when using a session after `.Detach()` |
| `ErrTransactionClosed` | `"transaction already committed or canceled"` | Returned when using a transaction after `.Commit()` or `.Cancel()` |
| `ErrTimeout` | `"timeout"` | Returned when an operation times out |
| `ErrNoNamespaceOrDB` | `"namespace or database or both are not set"` | Returned when operations require a namespace/database |

### Examples

```go
import "github.com/surrealdb/surrealdb.go/pkg/constants"

session, err := db.Attach(ctx)
if errors.Is(err, constants.ErrSessionsNotSupported) {
    fmt.Println("Use a WebSocket connection for sessions")
}
```

---

## See also

- [Error handling](/docs/reference/golang/concepts/error-handling.md) for error handling patterns and retry guidance
- [Types reference](/docs/reference/golang/api/types.md) for [`QueryResult`](/docs/reference/golang/api/types.md#queryresult) containing `QueryError`
- [DB reference](/docs/reference/golang/api/core/db.md) for methods that return these errors
- [Session reference](/docs/reference/golang/api/core/session.md) for `ErrSessionClosed` and `ErrSessionsNotSupported`
- [Transaction reference](/docs/reference/golang/api/core/transaction.md) for `ErrTransactionClosed` and `ErrTransactionsNotSupported`