Troubleshooting

​

Model Setup Issues

​

Model directory does not exist

​

Cannot auto-detect model type

1. Verify required files: Ensure the folder contains the required files for at least one model type:
   • Whisper: encoder.onnx, decoder.onnx, tokens.txt
   • Transducer: encoder.onnx, decoder.onnx, joiner.onnx, tokens.txt
   • VITS: model.onnx, tokens.txt, lexicon.txt
   • Zipvoice: encoder.onnx, decoder.onnx, vocoder.onnx (vocos/hifigan)
2. File names are case-sensitive: Ensure exact file names match requirements
3. Use explicit model type if detection fails:
   const recognizer = await createStreamingStt({
     modelPath: { type: 'asset', path: 'models/my-model' },
     modelType: 'whisper', // Explicit type
   });
   

​

getAssetPackPath() returns null

• The app was not installed from a bundle that includes the asset pack
• Install via the AAB: yarn android:pad or use bundletool
• Plain installDebug does not include the pack
• Use on-demand download if pack is not installed:
  const packPath = await getAssetPackPath('sherpa_models');
  if (!packPath) {
    // Download models or use fallback
    await downloadModelByCategory('stt', 'whisper-tiny');
  }
  

​

Audio Format Issues

​

STT: Audio format not supported

1. Convert audio files using FFmpeg:
   ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 output.wav
   
2. Use built-in conversion (if FFmpeg not disabled):
   import { convertAudioToWav16k } from 'react-native-sherpa-onnx/audio';
   
   const error = await convertAudioToWav16k(inputPath, outputPath);
   if (error) {
     console.error('Conversion failed:', error);
   }
   
3. Check audio properties:
   // Ensure correct format when reading audio
   const audioData = new Float32Array(samples);
   recognizer.acceptWaveform(audioData, 16000); // Must be 16kHz
   

​

TTS: Playback issues

1. Use correct sample rate returned by TTS:
   const result = await tts.generate({ text: 'Hello' });
   console.log('Sample rate:', result.sampleRate); // Use this for playback
   
2. Convert float samples for playback:
   // TTS returns float samples, convert to Int16 for player
   const int16Data = new Int16Array(result.samples.length);
   for (let i = 0; i < result.samples.length; i++) {
     int16Data[i] = Math.max(-32768, Math.min(32767, result.samples[i] * 32767));
   }
   

​

Build Issues

​

Android: bundletool not found (PAD)

• Add bundletool to PATH
• Or pass path explicitly: ./gradlew installDebugWithPad -Pbundletool=/path/to/bundletool
• Download bundletool: https://github.com/google/bundletool/releases

​

iOS: Framework or headers not found

1. Run pod install:
   cd ios
   pod install
   
2. Verify XCFramework:
   • Ensure sherpa-onnx XCFramework is downloaded
   • Check ios/Frameworks/sherpa_onnx.xcframework exists
   • If building locally, place framework in this location
3. Clean build:
   cd ios
   rm -rf Pods Podfile.lock
   pod install
   

​

JNI libraries not found (Android)

1. Check library paths: Ensure prebuilt libraries are in correct location:
   android/src/main/jniLibs/arm64-v8a/
   android/src/main/jniLibs/armeabi-v7a/
   
2. Verify ABI compatibility: Check your build.gradle includes required ABIs:
   android {
     defaultConfig {
       ndk {
         abiFilters 'arm64-v8a', 'armeabi-v7a'
       }
     }
   }
   

​

Performance Issues

​

Slow inference / High RTF

1. Enable hardware acceleration:
   const qnn = await getQnnSupport();
   if (qnn.canInit) {
     const recognizer = await createStreamingStt({
       modelPath: { type: 'asset', path: 'models/my-model' },
       provider: 'qnn', // Use NPU
     });
   }
   
2. Use quantized models:
   • Switch from FP32 to INT8 models
   • Example: Use sherpa-onnx-zipvoice-distill-int8 instead of full model
3. Adjust thread count:
   const recognizer = await createStreamingStt({
     modelPath: { type: 'asset', path: 'models/my-model' },
     numThreads: 4, // Adjust based on device
   });
   
4. See Performance Optimization for detailed tips

​

High memory usage / Out of memory

1. Use smaller models:
   // For low-RAM devices (<4GB)
   const modelPath = { 
     type: 'asset', 
     path: 'models/zipvoice-distill-int8' // ~104 MB vs ~605 MB
   };
   
2. Release resources when done:
   await recognizer.release();
   await tts.release();
   
3. Check memory before loading:
   try {
     const tts = await createTTS({ modelPath });
   } catch (error) {
     if (error.message.includes('Not enough free memory')) {
       // Use smaller model or show error
     }
   }
   

​

Execution Provider Issues

​

QNN not available

const qnn = await getQnnSupport();
console.log('Provider compiled:', qnn.providerCompiled);

​

NNAPI session fails

• This can be model-specific: some models may not be compatible with NNAPI
• Try with a different model or use CPU fallback:
  const nnapi = await getNnapiSupport();
  const provider = nnapi.canInit ? 'nnapi' : 'cpu';
  
• Check Android version: NNAPI requires Android 8.1+

​

Download Manager Issues

​

Model download fails

1. Check network connectivity
2. Verify model ID: Ensure the model ID is correct:
   const models = await listModelsByCategory('stt');
   console.log('Available models:', models.map(m => m.id));
   
3. Check disk space: Ensure sufficient storage available
4. Handle errors gracefully:
   try {
     await downloadModelByCategory('stt', 'whisper-tiny', {
       onProgress: (event) => console.log(`Progress: ${event.progress}%`),
     });
   } catch (error) {
     console.error('Download failed:', error.message);
   }
   

​

Archive extraction fails

1. Check if libarchive is disabled:
   • If sherpaOnnxDisableLibarchive=true is set, archive models won’t work
   • Solution: Remove the flag or use single-file models (.onnx)
2. Verify downloaded file:
   import { computeFileSha256 } from 'react-native-sherpa-onnx';
   
   const hash = await computeFileSha256(downloadedFilePath);
   console.log('File hash:', hash);
   
3. See Disable libarchive for details

​

Runtime Errors

​

”FFmpeg not available” error

1. Remove the flag if you need audio conversion:
   # gradle.properties
   # sherpaOnnxDisableFfmpeg=true  # Remove or comment out
   
2. Use external conversion:
   • Use another library for audio conversion
   • Or provide pre-converted audio files
3. See Disable FFmpeg for details

​

Invalid language code crashes (Whisper)

1. Use valid language codes:
   import { getWhisperLanguages } from 'react-native-sherpa-onnx/stt';
   
   const languages = await getWhisperLanguages();
   // Returns: [{ id: 'en', name: 'English' }, { id: 'de', name: 'German' }, ...]
   
2. Build language selector:
   const languages = await getWhisperLanguages();
   
   // In your UI component
   <Picker
     selectedValue={selectedLang}
     onValueChange={(value) => setSelectedLang(value)}
   >
     {languages.map(lang => (
       <Picker.Item key={lang.id} label={lang.name} value={lang.id} />
     ))}
   </Picker>
   

​

Zipvoice initialization fails

1. Verify model includes vocoder:
   • Check for vocos_24khz.onnx or hifigan.onnx in model directory
   • Distill models without vocoder will fail
2. Use complete Zipvoice model:
   // Good: Full model with vocoder
   modelPath: { type: 'asset', path: 'models/zipvoice-zh-en-emilia' }
   
   // Bad: Distill without vocoder (will fail)
   modelPath: { type: 'asset', path: 'models/zipvoice-distill-no-vocoder' }
   

​

Symbol Clashes

​

Multiple FFmpeg libraries crash

1. Disable FFmpeg in Sherpa-ONNX:
   # gradle.properties
   sherpaOnnxDisableFfmpeg=true
   
2. See Disable FFmpeg for details

​

Multiple libarchive libraries conflict

1. Disable libarchive in Sherpa-ONNX:
   # gradle.properties
   sherpaOnnxDisableLibarchive=true
   
2. See Disable libarchive for details

​

Getting Help

​

Debug Checklist

• Model files are present and complete
• Audio format matches requirements (16kHz, mono, 16-bit PCM for STT)
• Sufficient memory available (check device RAM)
• Correct execution provider for device
• Native libraries present for target ABI
• No conflicting native dependencies
• Latest SDK version installed
• Clean rebuild after configuration changes