gofr-dev/gofr · critical

failed to connect to SurrealDB: no valid database instance

Error message

failed to connect to SurrealDB: no valid database instance

What it means

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.

Source

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

package surrealdb

import (
	"context"
	"errors"
	"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

View on GitHub (pinned to 187eb24962)

Solutions

1. Verify the SurrealDB URL and provider configuration are correct and reachable.
2. Check SurrealDB server logs and connectivity (curl the endpoint) before starting the app.
3. Confirm the SDK version is compatible and the connect call isn't returning a nil instance.

Example fix

// before
SURREALDB_URL="http://localhost:8100"  // wrong port, server unreachable
// after
SURREALDB_URL="http://localhost:8000"  // correct reachable endpoint

u, _ := url.Parse(cfg.URL)
if u.Scheme != "http" && u.Scheme != "https" && u.Scheme != "ws" {
    return errors.New("invalid SurrealDB URL scheme")
}
if u.Host == "" { return errors.New("SurrealDB host missing") }

if err := client.Connect(ctx); err != nil {
    if errors.Is(err, surrealdb.ErrNoDatabaseInstance) {
        log.Fatalf("SurrealDB endpoint unreachable: %v", err)
    }
    return err
}

When it happens

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

Common situations: 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.

Related errors

• not connected to database
• both username and password must be provided
• %w: deleting document: %w
• %w: creating index: %w
• %w: deleting index: %w

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