Troubleshooting

This page serves as a quick reference for diagnosing common Android Offline Maps issues such as queued downloads, missing installed regions, tile server mismatches, preview-resource confusion, and interrupted background transfers. Let’s cover the most common ones below:

download() succeeds, but the region is not available offline

A successful download() call only means that the task was validated and added to the queue. The actual transfer, validation, and installation happen asynchronously. Continue observing downloadProgress and wait for the region to reach COMPLETED before treating it as available for offline display.

The first download does not start while the device is offline

The first download for a region requires network access because the SDK must retrieve the latest region details before enqueueing the task. If connectivity is lost after the task is queued, the task enters PAUSED_NETWORK and resumes automatically when a validated network is available.

A downloaded region is not displayed on the map

Check the following:

  • The current tile server is NGLTomTom.

  • The MapView lifecycle methods are forwarded correctly.

  • The camera is inside the downloaded region bounds and supports zoom range.

  • The map uses a predefined Bright or Dark style, or a custom style with compatible tile, sprite, glyph, and TileJSON URLs.

  • OfflineInstalledRegion.allTarsOk is true for the installed region.

The map page waits for previewBundleReady

The map page should not wait for previewBundleReady. That state is only used by the download page to control preview-resource preparation before downloads. The map page should set the style through the standard MapView lifecycle.

focusPreviewRegion() returns false

focusPreviewRegion() is only a camera helper. A false result means the SDK could not find indexable bounds for that region at that moment. It does not mean the installed region data is unavailable. Keep the current camera position, prompt the user to locate the region manually, or use an application-saved camera position.

Installed regions are missing after app start

Main-thread calls such as listInstalledRegions() may return only the cached in-memory snapshot during cold start. If the app needs a complete on-disk result immediately after launch, call listInstalledRegions() from a worker thread.

Download limits and expiration are not applied automatically

The SDK does not enforce account tiers, maximum storage by plan, or region expiration. Apply these policies in the application or backend, then use SDK APIs such as listInstalledRegions() and controlDownload(regionId, DownloadAction.DELETE) to enforce them.

Background downloads stop when the app process is killed

By default, downloads run in the application process. To continue long-running transfers in the background, the app must provide a DownloadForegroundHook and a compliant Android foreground Service. These downloads are not managed by Android DownloadManager or WorkManager automatically.