Troubleshooting

Use these checks to resolve common Offline Maps issues, including delayed download failures, Swift error handling, missing map data, and offline startup behavior.

The enqueue completion returned nil, but the download failed later

A nil completion error only means that the task was enqueued. Network transfer, decompression, and installation happen afterward. Read the final result from the progress listener.

Swift does not allow progress.error.code

Most likely the Objective-C NSError property is imported as Error?.

Convert it first:

1
let nsError = error as NSError

Then read nsError.domain, nsError.code, and nsError.userInfo.

The downloaded region does not appear on the map

Verify that:

  1. The download state is .completed.

  2. The map uses and registers a style from NGLRegionalOfflineStyleCatalog.

  3. The map engine is refreshed after returning from the download page.

  4. The active tile server is TomTom instead of any other provider.

The first download cannot start while offline

The first use requires connectivity to prepare shared preview resources. Offline styles can be displayed after these resources have been cached successfully.

Are system background downloads supported?

No. Regional map downloads currently use a normal URLSession, not a background session. Do not assume that downloads continue while the application is suspended.