{"record":{"id":"853dd1f794bc3309","repo":"gofr-dev/gofr","slug":"query-error","errorCode":null,"errorMessage":"query error","messagePattern":"query error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/gofr/datasource/surrealdb/surrealdb.go","lineNumber":24,"sourceCode":"\t\"fmt\"\n\t\"math\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/surrealdb/surrealdb.go\"\n\t\"github.com/surrealdb/surrealdb.go/pkg/models\"\n\t\"go.opentelemetry.io/otel/attribute\"\n\t\"go.opentelemetry.io/otel/trace\"\n)\n\nvar (\n\terrNotConnected             = errors.New(\"not connected to database\")\n\terrNoDatabaseInstance       = errors.New(\"failed to connect to SurrealDB: no valid database instance\")\n\terrInvalidCredentialsConfig = errors.New(\"both username and password must be provided\")\n\terrNoRecord                 = errors.New(\"no record found\")\n\terrNoResult                 = errors.New(\"no result found in query response\")\n\terrUnexpectedResult         = errors.New(\"unexpected result type: expected []any\")\n\terrQueryError               = errors.New(\"query error\")\n)\n\nconst (\n\tschemeHTTP      = \"http\"\n\tschemeHTTPS     = \"https\"\n\tschemeWS        = \"ws\"\n\tschemeWSS       = \"wss\"\n\tschemeMemory    = \"memory\"\n\tschemeMem       = \"mem\"\n\tschemeSurrealkv = \"surrealkv\"\n\tstatusOK        = \"OK\"\n\n\tdefaultTimeout = 30 * time.Second\n)\n\n// Config represents the configuration required to connect to SurrealDB.\ntype Config struct {\n\tHost       string","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/gofr-dev/gofr/blob/187eb24962502e91f1fee856230670958b66e89c/pkg/gofr/datasource/surrealdb/surrealdb.go#L6-L42","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Log/inspect the wrapped underlying error with errors.Is(err, errQueryError) and print the full chain to see SurrealDB's actual message","Validate the SurrealQL statement syntax and table/field names against your schema","Check that the number of query arguments matches the $placeholders in the query","Verify the SurrealDB user has permission (SELECT/CREATE/etc.) on the target namespace/database/table","Catch the error at call time and fail gracefully instead of processing a nil/empty result set"],"exampleFix":"// before\nrows, err := db.Query(ctx, \"SELEC * FROM users\")\nif err != nil { return err } // opaque \"query error\"\n// after\nrows, err := db.Query(ctx, \"SELECT * FROM users\")\nif err != nil {\n    if errors.Is(err, surrealdb.ErrQueryError) {\n        return fmt.Errorf(\"surreal query failed: %w\", err)\n    }\n    return err\n}","handlingStrategy":"try-catch","validationCode":"// validate before calling\nif strings.TrimSpace(query) == \"\" { return errors.New(\"empty SurrealQL query\") }\nif len(args) != strings.Count(query, \"$\") { return errors.New(\"arg/placeholder mismatch\") }","typeGuard":"func IsQueryError(err error) bool {\n    return err != nil && errors.Is(err, ErrQueryError)\n}","tryCatchPattern":"rows, err := db.Query(ctx, query, args...)\nif err != nil {\n    if errors.Is(err, surrealdb.ErrQueryError) {\n        log.Errorf(\"query failed: %v\", err)\n        return fmt.Errorf(\"data unavailable: %w\", err)\n    }\n    return err\n}","preventionTips":["Test every SurrealQL statement against a local SurrealDB instance in CI","Keep table/field names in constants shared with schema migrations","Match argument counts to $placeholders programmatically","Grant the DB user only the permissions it needs and verify them in staging"],"tags":["database","surrealdb","query","gofr"],"backgroundTag":"database-query-failed","analyzedSha":"187eb24962502e91f1fee856230670958b66e89c","analyzedAt":"2026-09-01T20:34:54.554Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}