Errors

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

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.

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

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

Represents a per-statement error within a query result. Returned in the Error field of QueryResult when an individual statement fails.

type QueryError struct {
    Message string
}

Methods:

• .Error() — returns the error message

• .Is(target) — returns true if target is a *QueryError

Examples

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

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 favor of ServerError)

Sentinel errors

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

Examples

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 for error handling patterns and retry guidance

• Types reference for QueryResult containing QueryError

• DB reference for methods that return these errors

• Session reference for ErrSessionClosed and ErrSessionsNotSupported

• Transaction reference for ErrTransactionClosed and ErrTransactionsNotSupported