{"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":"Error","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/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/react-native/src/Database.ts#L104-L140","documentation":"initLocalDatabase() runs during connect() for a local-mode database and requires the global __TursoProxy object that the native Turso module installs via JSI when the app binary starts. If the global is undefined, the JavaScript package is installed but the native Rust/JSI code was never compiled, linked, or registered into the running app, so no database can be created. The throw happens at `__TursoProxy.newDatabase(...)` guard time, before any file is opened.","triggerScenarios":"Running the app after adding @tursodatabase/react-native without rebuilding native binaries (no `pod install` / gradle build); running inside Expo Go, which cannot load custom native modules; executing the JS bundle in Jest or Node where no native runtime exists; a stale release build or a New Architecture / autolinking configuration that silently skipped the module.","commonSituations":"Fresh clone where a teammate ran `npm install` but not the iOS/Android native rebuild; CI unit tests importing Database.ts without mocking the native layer; upgrading React Native major versions and autolinking paths changing; debug works but release build strips the module due to proguard/minification rules.","solutions":["Rebuild the native app: `cd ios && pod install` then rebuild in Xcode, or a full gradle build for Android — JS-only reload (metro) is not enough","Verify @tursodatabase/react-native is in package.json dependencies (not devDependencies) so RN autolinking picks it up","Use a development build (expo prebuild / EAS dev build) instead of Expo Go, since Expo Go has no custom native modules","In unit tests, mock the global: `(global as any).__TursoProxy = mockTursoProxy` before constructing Database"],"exampleFix":"// before (Jest test importing the binding directly)\nimport { Database } from '@tursodatabase/react-native';\nawait new Database({ path: 'test.db' }).connect(); // throws: no native runtime\n\n// after\njest.mock('@tursodatabase/react-native', () => require('./__mocks__/tursoNative'));\n// or in a setup file for real apps: rebuild the native binary (pod install / gradle)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"declare global { var __TursoProxy: unknown | undefined; }\n\nexport function isTursoNativeLoaded(): boolean {\n  return typeof global.__TursoProxy !== 'undefined';\n}\n\nif (!isTursoNativeLoaded()) {\n  throw new Error('Turso native module not loaded — rebuild the app (pod install / gradle) or mock __TursoProxy in tests');\n}","tryCatchPattern":"try { await db.connect(); } catch (e) { if (e instanceof Error && /native module not loaded/.test(e.message)) { showRebuildHint(); return; } throw e; }","preventionTips":["Rebuild native binaries (pod install / gradle) whenever the native package changes — metro reload is not enough","Never assume the module exists in Expo Go or Jest; use dev builds and mocks","Add a startup probe with a clear remediation message so field reports are actionable"],"tags":["react-native","native-module","jsi","linking","expo"],"backgroundTag":"native-module-not-linked","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}