Skip to main content
The SDK provides comprehensive error handling through SDKError with specific error codes for different failure scenarios.

Basic Error Handling

try {
  await RunAnywhere.loadModel('my-model');
  final result = await RunAnywhere.generate('Hello');
  print(result.text);
} on SDKError catch (error) {
  print('Error: ${error.message}');
  print('Code: ${error.code}');
}

Error Categories

CategoryDescriptionCommon Errors
generalGeneral SDK errorsnotInitialized
llmLLM generation errorsgenerationFailed
sttSpeech-to-text errorssttNotAvailable
ttsText-to-speech errorsttsNotAvailable
voiceAgentVoice pipeline errorsvoiceAgentNotReady
downloadModel download errorsdownloadFailed
validationInput validation errorsvalidationFailed

Handling Specific Errors

try {
  await RunAnywhere.loadModel('my-model');
  final result = await RunAnywhere.generate('Hello!');
} on SDKError catch (error) {
  switch (error.code) {
    case SDKErrorCode.notInitialized:
      // SDK not initialized
      showError('Please restart the app');
      await RunAnywhere.initialize();
      break;

    case SDKErrorCode.modelNotFound:
      // Model not registered
      showError('Model not found. Please check the model ID.');
      break;

    case SDKErrorCode.modelNotDownloaded:
      // Model needs to be downloaded first
      showError('Model not downloaded. Downloading now...');
      await downloadModel('my-model');
      break;

    case SDKErrorCode.componentNotReady:
      // Component not loaded
      showError('Model not loaded. Loading now...');
      await RunAnywhere.loadModel('my-model');
      break;

    case SDKErrorCode.generationFailed:
      // Generation failed
      showError('Generation failed. Please try again.');
      break;

    default:
      showError('Error: ${error.message}');
  }
}

SDKError Factory Methods

Common error types with factory constructors:
// Check error types
if (error == SDKError.notInitialized()) {
  // Handle not initialized
}

if (error == SDKError.modelNotFound('model-id')) {
  // Handle model not found
}

if (error == SDKError.modelNotDownloaded('model-id')) {
  // Handle model not downloaded
}

if (error == SDKError.componentNotReady('LLM')) {
  // Handle component not ready
}

STT/TTS Specific Errors

try {
  final text = await RunAnywhere.transcribe(audioBytes);
} on SDKError catch (error) {
  switch (error.code) {
    case SDKErrorCode.sttNotAvailable:
      showError('Speech recognition not available. Load an STT model.');
      break;
    case SDKErrorCode.componentNotReady:
      showError('STT model not loaded.');
      await RunAnywhere.loadSTTModel('whisper-tiny-en');
      break;
    default:
      showError('Transcription failed: ${error.message}');
  }
}

try {
  final result = await RunAnywhere.synthesize('Hello');
} on SDKError catch (error) {
  switch (error.code) {
    case SDKErrorCode.ttsNotAvailable:
      showError('Text-to-speech not available. Load a TTS voice.');
      break;
    case SDKErrorCode.componentNotReady:
      showError('TTS voice not loaded.');
      await RunAnywhere.loadTTSVoice('piper-en-us-amy');
      break;
    default:
      showError('Synthesis failed: ${error.message}');
  }
}

Voice Agent Errors

try {
  final session = await RunAnywhere.startVoiceSession();
} on SDKError catch (error) {
  if (error.code == SDKErrorCode.voiceAgentNotReady) {
    // Check which component is missing
    final states = RunAnywhere.getVoiceAgentComponentStates();

    if (states.stt != ComponentLoadState.loaded) {
      showError('STT model not loaded');
      await RunAnywhere.loadSTTModel('whisper-tiny-en');
    }
    if (states.llm != ComponentLoadState.loaded) {
      showError('LLM model not loaded');
      await RunAnywhere.loadModel('smollm2-360m');
    }
    if (states.tts != ComponentLoadState.loaded) {
      showError('TTS voice not loaded');
      await RunAnywhere.loadTTSVoice('piper-en-us-amy');
    }
  }
}

Download Errors

try {
  await for (final progress in RunAnywhere.downloadModel('my-model')) {
    if (progress.state == DownloadProgressState.failed) {
      throw SDKError.downloadFailed('Download failed');
    }
    if (progress.state.isCompleted) break;
  }
} on SDKError catch (error) {
  showError('Failed to download model: ${error.message}');
  // Suggest checking internet connection
  showRetryOption();
}

User-Friendly Error Messages

Create a helper to convert errors to user-friendly messages:
String getUserFriendlyMessage(SDKError error) {
  switch (error.code) {
    case SDKErrorCode.notInitialized:
      return 'The app needs to restart. Please close and reopen the app.';
    case SDKErrorCode.modelNotFound:
      return 'The AI model could not be found. Please check your settings.';
    case SDKErrorCode.modelNotDownloaded:
      return 'This feature needs to download data first. Please connect to WiFi.';
    case SDKErrorCode.componentNotReady:
      return 'Loading AI features... Please wait a moment.';
    case SDKErrorCode.generationFailed:
      return 'Something went wrong. Please try again.';
    case SDKErrorCode.sttNotAvailable:
      return 'Voice recognition is not available right now.';
    case SDKErrorCode.ttsNotAvailable:
      return 'Voice output is not available right now.';
    default:
      return 'An error occurred. Please try again later.';
  }
}

Error Widget Pattern

class ErrorHandler extends StatelessWidget {
  final Widget child;
  final Function(SDKError) onError;

  const ErrorHandler({
    required this.child,
    required this.onError,
  });

  @override
  Widget build(BuildContext context) {
    return child;
  }

  static void handle(BuildContext context, SDKError error) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(getUserFriendlyMessage(error)),
        action: SnackBarAction(
          label: 'Retry',
          onPressed: () {
            // Implement retry logic
          },
        ),
      ),
    );
  }
}

See Also