gofr-dev/gofr · error

query error

Error message

query error

What it means

errQueryError is a sentinel error in GoFr's SurrealDB datasource returned by processQueryResults. It signals that SurrealDB reported an error while executing a query: the datasource wraps the raw database error with this sentinel (e.g. via fmt.Errorf("%w ...", errQueryError)) so callers can detect query failure with errors.Is. It does not indicate a connection problem, only that the submitted query failed at the database.

Source

Thrown at pkg/gofr/datasource/surrealdb/surrealdb.go:24

	"fmt"
	"math"
	"strings"
	"time"

	"github.com/surrealdb/surrealdb.go"
	"github.com/surrealdb/surrealdb.go/pkg/models"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

var (
	errNotConnected             = errors.New("not connected to database")
	errNoDatabaseInstance       = errors.New("failed to connect to SurrealDB: no valid database instance")
	errInvalidCredentialsConfig = errors.New("both username and password must be provided")
	errNoRecord                 = errors.New("no record found")
	errNoResult                 = errors.New("no result found in query response")
	errUnexpectedResult         = errors.New("unexpected result type: expected []any")
	errQueryError               = errors.New("query error")
)

const (
	schemeHTTP      = "http"
	schemeHTTPS     = "https"
	schemeWS        = "ws"
	schemeWSS       = "wss"
	schemeMemory    = "memory"
	schemeMem       = "mem"
	schemeSurrealkv = "surrealkv"
	statusOK        = "OK"

	defaultTimeout = 30 * time.Second
)

// Config represents the configuration required to connect to SurrealDB.
type Config struct {
	Host       string

View on GitHub (pinned to 187eb24962)

Solutions

1. Log/inspect the wrapped underlying error with errors.Is(err, errQueryError) and print the full chain to see SurrealDB's actual message
2. Validate the SurrealQL statement syntax and table/field names against your schema
3. Check that the number of query arguments matches the $placeholders in the query
4. Verify the SurrealDB user has permission (SELECT/CREATE/etc.) on the target namespace/database/table
5. Catch the error at call time and fail gracefully instead of processing a nil/empty result set

Example fix

// before
rows, err := db.Query(ctx, "SELEC * FROM users")
if err != nil { return err } // opaque "query error"
// after
rows, err := db.Query(ctx, "SELECT * FROM users")
if err != nil {
    if errors.Is(err, surrealdb.ErrQueryError) {
        return fmt.Errorf("surreal query failed: %w", err)
    }
    return err
}

// validate before calling
if strings.TrimSpace(query) == "" { return errors.New("empty SurrealQL query") }
if len(args) != strings.Count(query, "$") { return errors.New("arg/placeholder mismatch") }

func IsQueryError(err error) bool {
    return err != nil && errors.Is(err, ErrQueryError)
}

rows, err := db.Query(ctx, query, args...)
if err != nil {
    if errors.Is(err, surrealdb.ErrQueryError) {
        log.Errorf("query failed: %v", err)
        return fmt.Errorf("data unavailable: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Query/QueryWithArgs (or any datasource method that runs processQueryResults) with malformed SurrealQL, referencing non-existent tables/fields, syntax errors, or any other DB-side query failure returned by the SurrealDB client.

Common situations: Typos in SurrealQL statements, migrating schema changes that drop/rename tables used in queries, passing wrong argument counts to parameterized queries, or insufficient permissions for the SurrealDB user executing the query.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• failed to execute migration query
• surrealdb: %w
• no result found in query response
• sql: %w
• %w: %s: %w

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/853dd1f794bc3309. Report an issue: GitHub.