tursodatabase/turso · critical · Error

Turso native module not loaded

Error message

Turso native module not loaded

What it means

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.

Source

Thrown at bindings/react-native/src/Database.ts:122

    if (this._connected) {
      return;
    }

    if (this._isSync) {
      await this.initSyncDatabase();
    } else {
      this.initLocalDatabase();
    }

    this._connected = true;
  }

  /**
   * Initialize local-only database
   */
  private initLocalDatabase(): void {
    if (typeof __TursoProxy === 'undefined') {
      throw new Error('Turso native module not loaded');
    }

    const dbConfig = {
      path: this._opts.path,
      async_io: false, // use blocking IO for local database
    };

    // Create native database (path normalization happens in C++ JSI layer)
    this._nativeDb = __TursoProxy.newDatabase(this._opts.path, dbConfig);

    // Open database
    this._nativeDb.open();

    // Get connection
    this._connection = this._nativeDb.connect();
  }

  /**

View on GitHub (pinned to bad083fafb)

Solutions

1. 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
2. Verify @tursodatabase/react-native is in package.json dependencies (not devDependencies) so RN autolinking picks it up
3. Use a development build (expo prebuild / EAS dev build) instead of Expo Go, since Expo Go has no custom native modules
4. In unit tests, mock the global: `(global as any).__TursoProxy = mockTursoProxy` before constructing Database

Example fix

// before (Jest test importing the binding directly)
import { Database } from '@tursodatabase/react-native';
await new Database({ path: 'test.db' }).connect(); // throws: no native runtime

// after
jest.mock('@tursodatabase/react-native', () => require('./__mocks__/tursoNative'));
// or in a setup file for real apps: rebuild the native binary (pod install / gradle)

declare global { var __TursoProxy: unknown | undefined; }

export function isTursoNativeLoaded(): boolean {
  return typeof global.__TursoProxy !== 'undefined';
}

if (!isTursoNativeLoaded()) {
  throw new Error('Turso native module not loaded — rebuild the app (pod install / gradle) or mock __TursoProxy in tests');
}

try { await db.connect(); } catch (e) { if (e instanceof Error && /native module not loaded/.test(e.message)) { showRebuildHint(); return; } throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• @tursodatabase/sync-react-native: Native module not found. M
• Failed to get column name at index ${i}
• Unknown column type: ${kind}
• @tursodatabase/sync-react-native: Failed to install JSI bind
• @tursodatabase/sync-react-native: JSI bindings not found on

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