> ## 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.

# Error Handling

> Handle SDK errors gracefully

The SDK provides comprehensive error handling through `SDKError` with specific error codes for different failure scenarios.

## Basic Error Handling

```dart theme={null}
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

| Category     | Description             | Common Errors      |
| ------------ | ----------------------- | ------------------ |
| `general`    | General SDK errors      | notInitialized     |
| `llm`        | LLM generation errors   | generationFailed   |
| `stt`        | Speech-to-text errors   | sttNotAvailable    |
| `tts`        | Text-to-speech errors   | ttsNotAvailable    |
| `voiceAgent` | Voice pipeline errors   | voiceAgentNotReady |
| `download`   | Model download errors   | downloadFailed     |
| `validation` | Input validation errors | validationFailed   |

## Handling Specific Errors

```dart theme={null}
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:

```dart theme={null}
// 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

```dart theme={null}
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

```dart theme={null}
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

```dart theme={null}
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:

```dart theme={null}
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

```dart theme={null}
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

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/flutter/configuration">
    SDK configuration
  </Card>

  <Card title="Best Practices" icon="star" href="/flutter/best-practices">
    Optimization tips
  </Card>
</CardGroup>