tursodatabase/turso · critical

unable to load turso library: %w

Error message

unable to load turso library: %w

What it means

Panic raised by turso.InitLibrary (bindings/go/bindings.go:12-17) when turso-go-platform-libs' LoadTursoLibrary fails to locate or load the native Turso library for the configured LoadTursoLibraryConfig strategy. InitLibrary runs under sync.Once and registers the database/sql drivers, so the wrapped panic ('unable to load turso library: <cause>') aborts startup or the first query, whichever triggers initialization first.

Source

Thrown at bindings/go/bindings.go:16

package turso

import (
	"fmt"
	"sync"

	turso_libs "github.com/tursodatabase/turso-go-platform-libs"
)

var initLibrary sync.Once

func InitLibrary(strategy turso_libs.LoadTursoLibraryConfig) {
	initLibrary.Do(func() {
		library, err := turso_libs.LoadTursoLibrary(strategy)
		if err != nil {
			panic(fmt.Errorf("unable to load turso library: %w", err))
		}
		registerTursoDb(library)
		registerTursoSync(library)
	})
}

View on GitHub (pinned to bad083fafb)

Solutions

1. Read the wrapped cause after 'unable to load turso library:' — it names the file, path, or platform problem
2. Ship the native library inside the artifact (COPY it into the image) and configure LoadTursoLibraryConfig with a strategy that finds it there
3. Call InitLibrary explicitly at program start instead of relying on lazy registration, so failure happens where you can log and exit cleanly
4. Verify GOOS/GOARCH support and align go.mod versions of tursodatabase/turso-go and turso-go-platform-libs; 'go clean -modcache' if a cached artifact is corrupt

Example fix

// before: initialization happens lazily, so the first query panics mid-request
db, err := sql.Open("turso", dsn)

// after: initialize at startup with an explicit strategy so a missing
// library fails fast in a place you control
func main() {
    log.SetFlags(0)
    turso.InitLibrary(turso_libs.LoadTursoLibraryConfig{LoadStrategy: "mixed"})
    db, err := sql.Open("turso", dsn)
    ...
}

// Call this first thing in main() so a missing library fails fast with a
// clear message instead of panicking on the first query.
func initTurso(cfg turso_libs.LoadTursoLibraryConfig) (err error) {
	defer func() {
		if r := recover(); r != nil {
			err = fmt.Errorf("turso library init failed: %v", r)
		}
	}()
	turso.InitLibrary(cfg)
	return nil
}

// usage
if err := initTurso(turso_libs.LoadTursoLibraryConfig{LoadStrategy: "mixed"}); err != nil {
	log.Fatalf("%v", err)
}

// Go's recover is the catch; wrap the once-only init and exit loudly.
func main() {
	defer func() {
		if r := recover(); r != nil {
			log.Fatalf("startup failed: %v", r) // includes 'unable to load turso library: <cause>'
		}
	}()
	turso.InitLibrary(turso_libs.LoadTursoLibraryConfig{LoadStrategy: "mixed"})
	// ... rest of program

When it happens

Trigger: Calling sql.Open / driver registration with no native library available: a 'local' strategy pointing at a missing or wrong-architecture file; a scratch/distroless container without the .so/.dylib/.dll; an unsupported GOOS/GOARCH pair; a corrupted or partially downloaded library; air-gapped environments where the library cannot be fetched.

Common situations: Minimal Docker images that stripped the shared library; CI cross-compilation producing platform mismatches; version drift between tursodatabase/turso-go and turso-go-platform-libs in go.mod; read-only or offline deploy targets.

Related errors

• Database not connected. Call connect() first.
• ARM64 architecture is not supported on Linux yet
• Unable to load necessary native library

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/6a9334c2eb034172. Report an issue: GitHub.