# Error Handling

This section shows how to handle `NavigationError` cases consistently and present clear retry or recovery actions when offline initialization, data, or network conditions fail.

Handle _NavigationError_ cases first:

```swift
do {
    try await performOfflineAction()
} catch let error as NavigationError {
    switch error {
    case .engineNotInitialized:
        showInitializationRequired()
    case .dataNotReady, .regionNotFound:
        showDataUnavailable(error.localizedDescription)
    case .interrupted, .engineSuperseded:
        showRetry(error.localizedDescription)
    default:
        showOfflineError(code: error.code, message: error.message)
    }
} catch {
    showOfflineError(code: "unknown", message: error.localizedDescription)
}
```

| Error or state | Common cause | Recommended handling |
| --- | --- | --- |
| `engineNotInitialized` | Initialization has not been started | Call initializeOffline and retry |
| `invalidConfig` | Different immutable configurations were used during one lifecycle | Use one configuration source; start a new lifecycle after a complete shutdown |
| `dataNotReady` | Required routing data has not been downloaded or loaded | Prompt the user to download the required region |
| `dataVersionMismatch` | Local data is incompatible with the engine's supported range | Prompt the user to update region data and record health diagnostics |
| `interrupted` | Shutdown is in progress or the task was canceled | Wait for the lifecycle to stabilize and retry |
| `engineSuperseded` | The engine was replaced while the operation was waiting | Check for duplicate engine creation or shutdown calls |
| `Network unavailable or restricted` | No network connection or the Wi-Fi-only policy is not satisfied | Preserve partial data and provide a recovery action |

> **Screen behavior:** _Do not log an initialization failure and continue loading the catalog. Show a clear failure state and a retry action. The retry action should call_ `initializeOffline` _and then reload the catalog._