{"record":{"id":"6a9334c2eb034172","repo":"tursodatabase/turso","slug":"unable-to-load-turso-library-w","errorCode":null,"errorMessage":"unable to load turso library: %w","messagePattern":"unable to load turso library: %w","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"bindings/go/bindings.go","lineNumber":16,"sourceCode":"package turso\n\nimport (\n\t\"fmt\"\n\t\"sync\"\n\n\tturso_libs \"github.com/tursodatabase/turso-go-platform-libs\"\n)\n\nvar initLibrary sync.Once\n\nfunc InitLibrary(strategy turso_libs.LoadTursoLibraryConfig) {\n\tinitLibrary.Do(func() {\n\t\tlibrary, err := turso_libs.LoadTursoLibrary(strategy)\n\t\tif err != nil {\n\t\t\tpanic(fmt.Errorf(\"unable to load turso library: %w\", err))\n\t\t}\n\t\tregisterTursoDb(library)\n\t\tregisterTursoSync(library)\n\t})\n}\n","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/go/bindings.go#L1-L22","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause after 'unable to load turso library:' — it names the file, path, or platform problem","Ship the native library inside the artifact (COPY it into the image) and configure LoadTursoLibraryConfig with a strategy that finds it there","Call InitLibrary explicitly at program start instead of relying on lazy registration, so failure happens where you can log and exit cleanly","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"],"exampleFix":"// before: initialization happens lazily, so the first query panics mid-request\ndb, err := sql.Open(\"turso\", dsn)\n\n// after: initialize at startup with an explicit strategy so a missing\n// library fails fast in a place you control\nfunc main() {\n    log.SetFlags(0)\n    turso.InitLibrary(turso_libs.LoadTursoLibraryConfig{LoadStrategy: \"mixed\"})\n    db, err := sql.Open(\"turso\", dsn)\n    ...\n}","handlingStrategy":"validation","validationCode":"// Call this first thing in main() so a missing library fails fast with a\n// clear message instead of panicking on the first query.\nfunc initTurso(cfg turso_libs.LoadTursoLibraryConfig) (err error) {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\terr = fmt.Errorf(\"turso library init failed: %v\", r)\n\t\t}\n\t}()\n\tturso.InitLibrary(cfg)\n\treturn nil\n}\n\n// usage\nif err := initTurso(turso_libs.LoadTursoLibraryConfig{LoadStrategy: \"mixed\"}); err != nil {\n\tlog.Fatalf(\"%v\", err)\n}","typeGuard":null,"tryCatchPattern":"// Go's recover is the catch; wrap the once-only init and exit loudly.\nfunc main() {\n\tdefer func() {\n\t\tif r := recover(); r != nil {\n\t\t\tlog.Fatalf(\"startup failed: %v\", r) // includes 'unable to load turso library: <cause>'\n\t\t}\n\t}()\n\tturso.InitLibrary(turso_libs.LoadTursoLibraryConfig{LoadStrategy: \"mixed\"})\n\t// ... rest of program","preventionTips":["Call InitLibrary explicitly at startup — never rely on lazy registration for a program-critical library","Bake the native library into the container image and verify it with a container healthcheck/smoke test","Print the wrapped cause: it distinguishes missing file vs wrong architecture vs download failure","Pin tursodatabase/turso-go and turso-go-platform-libs to tested, matching versions in go.mod"],"tags":["go","native-library","deployment","panic","initialization"],"backgroundTag":"native-library-load-failure","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}