tursodatabase/turso · critical · Error

@tursodatabase/sync-react-native: Failed to install JSI…

Error message

@tursodatabase/sync-react-native: Failed to install JSI bindings. Make sure the New Architecture is enabled.

What it means

The native module exists, but TursoNative.install() returned false, meaning the JSI bindings could not be installed into the JavaScript runtime. This SDK passes all database calls through JSI, which on React Native requires the New Architecture; on the legacy architecture (or a JS runtime where JSI is unavailable, such as remote Chrome debugging) install() fails and the module-init code throws at import time.

Solutions

  1. Enable the New Architecture: Android - set newArchEnabled=true in android/gradle.properties; iOS - set RCT_NEW_ARCH_ENABLED=1 (or :rn_new_architecture_enabled => true in the Podfile) and re-run pod install
  2. Upgrade React Native to a version that supports the New Architecture (>= 0.68, current recommended line)
  3. Turn off remote JS debugging (use Hermes/Flipper-based debugging instead) - remote debugging executes JS in Chrome where JSI proxies cannot live
  4. Do a full rebuild and reinstall of the app after flipping the flag; a reload will not pick it up

Example fix

# android/gradle.properties - before
newArchEnabled=false

# after
newArchEnabled=true

# then: cd android && ./gradlew clean && cd ios && pod install (with RCT_NEW_ARCH_ENABLED=1), full rebuild
Defensive patterns

Strategy: validation

Validate before calling

// Fail with a clear message before importing, instead of the raw JSI error
import { NativeModules, Platform } from 'react-native';
const isNewArch = (global as any).RN$Bridgeless ?? false; // proxy for new-arch runtime
if ((Platform.OS === 'ios' || Platform.OS === 'android') && !isNewArch && __DEV__) {
  console.warn('Turso RN SDK needs the New Architecture - set newArchEnabled=true / RCT_NEW_ARCH_ENABLED=1');
}

Try / catch

try { await import('@tursodatabase/sync-react-native'); } catch (e) { if (String(e.message).includes('Failed to install JSI bindings')) { throw new Error('Enable the RN New Architecture (newArchEnabled=true / RCT_NEW_ARCH_ENABLED=1) and rebuild, or disable remote JS debugging'); } throw e; }

Prevention

When it happens

Trigger: Running the app with the New Architecture disabled (newArchEnabled=false on Android, or RCT_NEW_ARCH_ENABLED unset on iOS), an RN version too old for TurboModules (< 0.68), or having Chrome remote JS debugging active - that moves JS execution out of the RN runtime where __TursoProxy cannot be installed.

Common situations: Adding the SDK to an older RN app that has not migrated to the New Architecture; a developer enabling 'Debug with Chrome' (remote debugging) which disables JSI even on a new-arch app; CI build flavors that default newArchEnabled back to false after an RN upgrade.

Related errors

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/5147045cab99ac89. Report an issue: GitHub.

Appendix: source

Thrown at bindings/react-native/src/index.ts:64

// Export file system configuration function
export { setFileSystemImpl } from './internal/ioProcessor';

// Get the native module
const TursoNative: TursoNativeModule | undefined = NativeModules.Turso;

// Check if native module is available
if (!TursoNative) {
  throw new Error(
    `@tursodatabase/sync-react-native: Native module not found. Make sure you have properly linked the library.\n` +
    `- iOS: Run 'pod install' in your ios directory\n` +
    `- Android: Make sure the package is properly included in your MainApplication.java`
  );
}

// Install the JSI bindings
const installed = TursoNative.install();
if (!installed) {
  throw new Error(
    '@tursodatabase/sync-react-native: Failed to install JSI bindings. Make sure the New Architecture is enabled.'
  );
}

// Get the proxy that was installed on the global object
// __TursoProxy is declared globally in types.ts
const TursoProxy: TursoProxyType = __TursoProxy;

if (!TursoProxy) {
  throw new Error(
    '@tursodatabase/sync-react-native: JSI bindings not found on global object. This is a bug.'
  );
}

/**
 * Helper function to construct a database path in a writable directory.
 *
 * @param filename - Database filename (e.g., 'mydb.db')

View on GitHub (pinned to 244cde92a7)