gofr-dev/gofr · error

surrealdb: %w

Error message

surrealdb: %w

What it means

This error wraps failures from querying the current migration version in the SurrealDB migrator. getLastMigration runs getLastSurrealDBGoFrMigration via s.SurrealDB.Query; if the query itself errors (connection, auth, query rejection) the error is wrapped with the `surrealdb:` prefix and -1 is returned. It is a migration-state lookup failure, not a data problem.

Source

Thrown at pkg/gofr/migration/surreal_db.go:108

	case uint64:
		if n > math.MaxInt64 {
			return 0
		}

		return int64(n)
	case float64:
		return int64(n)
	default:
		return 0
	}
}

func (s surrealMigrator) getLastMigration(c *container.Container) (int64, error) {
	var lastMigration int64

	result, err := s.SurrealDB.Query(context.Background(), getLastSurrealDBGoFrMigration, nil)
	if err != nil {
		return -1, fmt.Errorf("surrealdb: %w", err)
	}

	if len(result) > 0 {
		if row, ok := result[0].(map[string]any); ok {
			lastMigration = surrealVersionToInt64(row["version"])
		}
	}

	c.Debugf("surrealDB last migration fetched value is: %v", lastMigration)

	lm2, err := s.migrator.getLastMigration(c)
	if err != nil {
		return -1, err
	}

	return max(lastMigration, lm2), nil
}

View on GitHub (pinned to 187eb24962)

Solutions

1. Check the inner wrapped error for the SurrealDB cause (auth, permission, connection).
2. Verify namespace/database selection and that the gofr_migrations table exists.
3. Reconnect or re-authenticate to SurrealDB, then retry the migration.
4. Confirm the configured SurrealDB role can SELECT from the migrations table.

Example fix

// before: reading last migration with expired/unstable WS connection
app.Migrate()
// after: ensure stable connection and retry on transient failure
for i := 0; i < 3; i++ {
	if err := pingSurreal(db); err == nil { break }
	time.Sleep(time.Second)
}
app.Migrate()

if err := db.Health(ctx); err != nil {
	return fmt.Errorf("surrealdb unhealthy before migration: %w", err)
}

if s.SurrealDB == nil {
	return errors.New("surrealdb datasource not configured")
}

var last int64
var err error
for i := 0; i < 3; i++ {
	last, err = migrator.getLastMigration(c)
	if err == nil { break }
	time.Sleep(500 * time.Millisecond) // transient WS drops
}
if err != nil { return fmt.Errorf("last migration lookup failed: %w", err) }

When it happens

Trigger: Calling Migration.Run with a SurrealDB datasource when the SELECT of the gofr_migrations table fails — server unreachable, session expired, table dropped mid-run, invalid query.

Common situations: SurrealDB restarted between migration steps; WebSocket connection dropped; wrong namespace/database selected so the table isn't visible; RBAC permissions deny SELECT on the migrations table.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• failed to execute migration query
• query error
• sql: %w
• %w: %s: %w
• regex pattern '^...$' is not supported, use mux patterns ins

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