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:
| 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
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
