{"record":{"id":"19c1582ea57e0ae7","repo":"tursodatabase/turso","slug":"turso-native-module-not-loaded","errorCode":null,"errorMessage":"Turso native module not loaded","messagePattern":"Turso native module not loaded","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"bindings/react-native/src/Database.ts","lineNumber":122,"sourceCode":"    if (this._connected) {\n      return;\n    }\n\n    if (this._isSync) {\n      await this.initSyncDatabase();\n    } else {\n      this.initLocalDatabase();\n    }\n\n    this._connected = true;\n  }\n\n  /**\n   * Initialize local-only database\n   */\n  private initLocalDatabase(): void {\n    if (typeof __TursoProxy === 'undefined') {\n      throw new Error('Turso native module not loaded');\n    }\n\n    const dbConfig = {\n      path: this._opts.path,\n      async_io: false, // use blocking IO for local database\n    };\n\n    // Create native database (path normalization happens in C++ JSI layer)\n    this._nativeDb = __TursoProxy.newDatabase(this._opts.path, dbConfig);\n\n    // Open database\n    this._nativeDb.open();\n\n    // Get connection\n    this._connection = this._nativeDb.connect();\n  }\n\n  /**","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/react-native/src/Database.ts#L104-L140","documentation":"Thrown by initLocalDatabase() during connect() when the JSI global __TursoProxy is not present on the JS runtime. The React Native binding is a thin TypeScript layer over a C++ JSI module that installs __TursoProxy as a runtime global (cpp/TursoHostObject.cpp). If the native part of @tursodatabase/sync-react-native was never built, linked, or is running in a runtime without JSI, the global is undefined and every local-only Database construction fails.","triggerScenarios":"Creating `new Database({ path })` (no url) and calling `await db.connect()` while __TursoProxy is undefined: running the app without rebuilding the native binary after adding the dependency, skipping `cd ios && pod install`, debugging JS remotely in Chrome (the Chrome remote debugger replaces the JSI runtime with a plain JS engine that has no JSI globals), or running inside Expo Go where custom native code is not included.","commonSituations":"Fresh install where `npm install @tursodatabase/sync-react-native` ran but the iOS pods / Android gradle build were never refreshed; switching a project to the new architecture or upgrading React Native without rebuilding the app binary; enabling 'Debug JS Remotely' which detaches JSI; using Expo Go instead of a development build (`npx expo run:ios`).","solutions":["Disable remote JS debugging (Chrome debugger) — JSI only works with on-device/Hermes debugging via Flipper or the new debugger; then reload","Rebuild the native app completely: `cd ios && pod install && cd .. && npx react-native run-ios` (or `./gradlew assembleDebug` on Android) so the JSI host object is compiled in","If using Expo, switch from Expo Go to a development build (`npx expo run:ios` / `run-android`) since Expo Go cannot load custom native modules","Verify android/build.gradle has minSdkVersion 21+ and that the package is autolinked (check it appears in `pod install` output / MainActivity modules)","As a last resort, clean and rebuild: `watchman watch-del-all`, delete node_modules, ios/Pods, and build directories, then reinstall"],"exampleFix":"// before: app works in normal mode but throws 'Turso native module not loaded' when remote debugging\n// Dev Menu -> Debug JS Remotely -> reload:\nconst db = new Database({ path: getDbPath('local.db') });\nawait db.connect(); // throws: __TursoProxy is undefined in the Chrome debug runtime\n\n// after: keep JS execution on device (Hermes) and rebuild native after install\n// package.json scripts stay the same; just avoid remote JS debugging and rebuild:\n//   cd ios && pod install && cd ..\n//   npx react-native run-ios\nconst db = new Database({ path: getDbPath('local.db') });\nawait db.connect();","handlingStrategy":"validation","validationCode":"// Before constructing a Database, confirm the JSI global exists\nimport { getDbPath, Database } from '@tursodatabase/sync-react-native';\n\ndeclare const __TursoProxy: unknown;\n\nexport function nativeModuleAvailable(): boolean {\n  return typeof __TursoProxy !== 'undefined';\n}\n\nif (!nativeModuleAvailable()) {\n  throw new Error(\n    'Turso native module missing: rebuild the app (pod install / gradle) and disable remote JS debugging'\n  );\n}\nconst db = new Database({ path: getDbPath('local.db') });","typeGuard":"declare const __TursoProxy: unknown;\n\nfunction hasTursoNative(globalThis: Record<string, unknown>): boolean {\n  return typeof globalThis['__TursoProxy'] !== 'undefined';\n}","tryCatchPattern":"try {\n  await db.connect();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('native module not loaded')) {\n    // Environment problem, not a data problem: instruct rebuild / disable remote debug\n    showSetupError('Rebuild the native app and disable remote JS debugging (JSI required).');\n  }\n  throw e;\n}","preventionTips":["Always rebuild the native app after installing or upgrading the package (pod install on iOS, gradle build on Android)","Never run the app with Chrome remote JS debugging when using JSI-based libraries; use on-device debugging","Use an Expo development build, not Expo Go, for custom native modules","Fail fast at startup with a typeof __TursoProxy check so the failure names the environment cause"],"tags":["react-native","jsi","native-module","setup","local-database"],"backgroundTag":"native-module-not-linked","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}