Troubleshooting
Common issues with @mhpdev/react-native-speech and how to resolve them.
The native module cannot be found
The library is built on Turbo Modules and only supports the New Architecture. If the native module is missing at runtime, verify that the New Architecture is enabled — React Native 0.76+ has it enabled by default; on React Native 0.68–0.75 you must enable it first. See the React Native New Architecture guide.
Expo Go is not supported
The library requires a native build. In Expo projects, run npx expo prebuild (see Installation) and use a development build instead of Expo Go.
Speech fails to start on Android
The Android module initializes the text-to-speech engine lazily and rejects with speech_error if initialization fails. Common causes:
- No text-to-speech engine is installed or the engine lacks voice data for the requested language. Use
Speech.openVoiceDataInstaller()to send the user to the system installer, andSpeech.getEngines()/Speech.setEngine(name)to switch engines. - The text is
null— the module rejects calls with null text.
Text exceeds the maximum input length
On Android, text longer than Speech.maxInputLength is rejected. Check the constant before calling speak() and split long text into smaller utterances on the JavaScript side.
Pause and resume do nothing on older Android
pause and resume require Android 8.0 (API 26+). On lower API levels these calls cannot pause the engine — guard your UI with Platform.Version >= 26, as the example project does.
Switching engines fails
Speech.setEngine rejects with engine_error when the requested engine name is not available on the device. Always resolve the engine name from Speech.getEngines() instead of hardcoding one.
Voice data installer cannot open
Speech.openVoiceDataInstaller() rejects with UNSUPPORTED_OPERATION when the device has no activity that can handle TTS voice data installation.
iOS audio behaves unexpectedly with the silent switch
silentMode is iOS only:
obey(default) keeps the app's audio session unchanged and follows system default behavior.respectsilences speech with the ringer switch — use it for non-critical audio.ignoreplays speech even with the ringer off — use it for critical audio.
ducking: true takes priority over silentMode and should only be used for critical announcements such as navigation.
Still stuck?
- Search the issue tracker and open a new issue if the problem persists.
- Check the releases page for version-specific notes and fixes.