Handle Structured Errors
This guide covers how to deal with structured errors encountered while downloading offline map packages. Offline Maps operations can report errors through the downloadRegion completion handler before a task is accepted, and through progress.error after a task has been enqueued.
Since, in Swift, progress.error is exposed as Error?. Cast it to NSError to read the Offline Maps error domain, code, and diagnostic userInfo values.
Following is the table with references for errors:
| Swift error code | Meaning | Recommended action |
|---|---|---|
.network | Unclassified network error | Check connectivity and retry |
.networkUnavailable | No connection, DNS failure, or host connection failure | Wait for connectivity |
.requestTimedOut | Request timed out | Offer retry |
.httpStatus | Non-2xx HTTP response | Record the HTTP status and verify the service |
.invalidResponse | Invalid catalog or region response | Verify server data |
.storage | Generic storage error | Check device storage |
.fileSystem | File create, read, or write failure | Check storage and retry |
.insufficientStorage | Insufficient free storage | Ask the user to free space |
.invalidPackage | Corrupt or unsupported package | Retry or verify the server package |
.packageDecompression | Package decompression failed | Retry the download |
.packageInstallation | Package installation failed | Check storage and retry |
.invalidRegion | Invalid or unknown region | Refresh the catalog |
.previewNotReady | Shared preview resources are not ready | Wait for resource preparation |
.styleNotCached | The offline style is not cached | Use an SDK offline style and prepare preview resources |
.noInstalledRegions | No installed region is available | Ask the user to download a region |
.cancelled | Download was cancelled or paused | Resume according to the product flow |
.unknown | Unclassified or legacy error | Record the complete error |
.downloadAlreadyActive | The same region already has an active task | Reuse, wait for, cancel, or delete the existing task |
.previewDatabaseOpen | The native engine could not open the validated Preview database | Keep the task incomplete and record the database path and underlying error |
.previewRollbackFailed | Preview activation failed and rollback was incomplete | Stop completion and record the rollback error array |
.unsupportedTileServer | The active tile server has no supported Regional Offline packages | Select NGLTomTom before configuring or using Regional Offline |
progress.errorMessage remains available for compatibility. New integrations should use progress.error.