Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runanywhere.ai/llms.txt

Use this file to discover all available pages before exploring further.

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('Type: ${error.type}');
}

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.type) {
    case SDKErrorType.notInitialized:
      // SDK not initialized
      showError('Please restart the app');
      await RunAnywhere.initialize();
      break;

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

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

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

    case SDKErrorType.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.type) {
    case SDKErrorType.sttNotAvailable:
      showError('Speech recognition not available. Load an STT model.');
      break;
    case SDKErrorType.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.type) {
    case SDKErrorType.ttsNotAvailable:
      showError('Text-to-speech not available. Load a TTS voice.');
      break;
    case SDKErrorType.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.type == SDKErrorType.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('my-model', '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.type) {
    case SDKErrorType.notInitialized:
      return 'The app needs to restart. Please close and reopen the app.';
    case SDKErrorType.modelNotFound:
      return 'The AI model could not be found. Please check your settings.';
    case SDKErrorType.modelNotDownloaded:
      return 'This feature needs to download data first. Please connect to WiFi.';
    case SDKErrorType.componentNotReady:
      return 'Loading AI features... Please wait a moment.';
    case SDKErrorType.generationFailed:
      return 'Something went wrong. Please try again.';
    case SDKErrorType.sttNotAvailable:
      return 'Voice recognition is not available right now.';
    case SDKErrorType.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

Configuration

SDK configuration

Best Practices

Optimization tips