Troubleshooting

Expo Go fails

Expo Go does not contain the native ONNX and filesystem modules. Create a development build with expo prebuild and expo run:ios or expo run:android.

speak() reports no player

Pass createExpoAudioPlayer(ExpoAudio), createRNSoundPlayer(Sound), createBrowserAudioPlayer(), or your own AudioPlayer. Use generate() when playback is not needed.

First run looks slow

The first run downloads model and phonemizer assets and initializes ONNX. Inspect getModelCacheInfo() before choosing between a download UI and a short initialization state.

Download keeps restarting

The SDK discards partial .download files. Ensure the app has writable storage and stable access to Hugging Face, or set modelBaseURL to your mirror. Use redownloadModel() once to repair a corrupt model.

ONNX module is null on Android

The package runs a compatibility patch during postinstall and registers its Android package. Reinstall dependencies, clean the native build, and rebuild. Do not manually add a conflicting ONNX package registration.

Bundled files are missing

Bundled assets are copied at native build time. After modifying assets/kittentts, run expo prebuild --clean and rebuild the native app. Test a clean install to ensure the result is not reading an older cache.

Web fails to load WASM

Reload after dependency changes. If Content Security Policy or CDN access blocks the default files, self-host matching ONNX Runtime Web assets and pass ortWasmPath.

For reproducible reports, include package version, React Native or Expo version, platform, model, full error code, and a minimal reproduction: React Native issues.