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:

1
do {
2
    try await performOfflineAction()
3
} catch let error as NavigationError {
4
    switch error {
5
    case .engineNotInitialized:
6
        showInitializationRequired()
7
    case .dataNotReady, .regionNotFound:
8
        showDataUnavailable(error.localizedDescription)
9
    case .interrupted, .engineSuperseded:
10
        showRetry(error.localizedDescription)
11
    default:
12
        showOfflineError(code: error.code, message: error.message)
13
    }
14
} catch {
15
    showOfflineError(code: "unknown", message: error.localizedDescription)
16
}

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.