{"record":{"id":"32e461f20e911584","repo":"gofr-dev/gofr","slug":"failed-to-connect-to-surrealdb-no-valid-database","errorCode":null,"errorMessage":"failed to connect to SurrealDB: no valid database instance","messagePattern":"failed to connect to SurrealDB: no valid database instance","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/gofr/datasource/surrealdb/surrealdb.go","lineNumber":19,"sourceCode":"package surrealdb\n\nimport (\n\t\"context\"\n\t\"errors\"\n\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","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/gofr-dev/gofr/blob/187eb24962502e91f1fee856230670958b66e89c/pkg/gofr/datasource/surrealdb/surrealdb.go#L1-L37","documentation":"errNoDatabaseInstance is returned by connectToDatabase when, after attempting to establish a connection, the SurrealDB client ends up with no valid underlying database instance. gofr wraps it with the message \"failed to connect to SurrealDB: no valid database instance\", signaling the connection attempt itself did not yield a usable client.","triggerScenarios":"Calling Connect (directly or via New) where the provider/URL resolution yields no database instance — e.g. invalid or unknown provider causing the connection step to silently produce a nil instance that connectToDatabase then rejects.","commonSituations":"Misconfigured SurrealDB endpoint (bad scheme/host), unknown provider string so no base URL is derived, network failure during connect, or SurrealDB SDK returning a nil result without a distinct error.","solutions":["Verify the SurrealDB URL and provider configuration are correct and reachable.","Check SurrealDB server logs and connectivity (curl the endpoint) before starting the app.","Confirm the SDK version is compatible and the connect call isn't returning a nil instance."],"exampleFix":"// before\nSURREALDB_URL=\"http://localhost:8100\"  // wrong port, server unreachable\n// after\nSURREALDB_URL=\"http://localhost:8000\"  // correct reachable endpoint","handlingStrategy":"validation","validationCode":"u, _ := url.Parse(cfg.URL)\nif u.Scheme != \"http\" && u.Scheme != \"https\" && u.Scheme != \"ws\" {\n    return errors.New(\"invalid SurrealDB URL scheme\")\n}\nif u.Host == \"\" { return errors.New(\"SurrealDB host missing\") }","typeGuard":null,"tryCatchPattern":"if err := client.Connect(ctx); err != nil {\n    if errors.Is(err, surrealdb.ErrNoDatabaseInstance) {\n        log.Fatalf(\"SurrealDB endpoint unreachable: %v\", err)\n    }\n    return err\n}","preventionTips":["Health-check the SurrealDB endpoint in readiness probes before app traffic.","Validate URL/provider configuration at startup.","Pin compatible surrealdb.go SDK versions in go.mod."],"tags":["surrealdb","connection","configuration"],"backgroundTag":"database-connection-failed","analyzedSha":"187eb24962502e91f1fee856230670958b66e89c","analyzedAt":"2026-09-01T20:34:54.554Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}