Troubleshooting

Common issues integrators hit when setting up map data, and how to diagnose them.

The fallback to the onboard region store does not engage

When connectivity is cut the SDK should keep operating — from the cache within the prefetched area, and from the onboard region store beyond it. If operation stops or the map display goes blank instead, check the following in order:

1. A regionStorePath was passed to buildSdkConfiguration. Without it the SDK has no onboard region store and there is nothing to fall back to.
2. The region store contains data for the current location. The onboard store can only cover what is installed in it. If your region store ships with only a small area, drive testing must stay inside that area.
3. The keystore matches the region store. A mismatched or missing keystore prevents the SDK from reading the region store. You will see a region-store-related error in logcat at start-up. If you suspect the map or keystore is corrupted rather than misconfigured, see Map corruption recovery.
4. Sufficient disk space. If regionStorePath or updateStoragePath cannot grow, updates fail and the onboard data drifts out of date. Free up space and restart the app.

Region downloads never start

Two switches are off by default; either one silently blocks manual downloads:

1. Update processing is disabled every time the SDK initializes. Call regionStore.setUpdatesEnabled(true) before scheduling downloads or deletions. See Manage onboard regions.
2. Manual downloads are refused on metered connections by default. On a device with only a mobile connection, download fails unless you set manualUpdateNetworkConfig to NetworkConnectivityConfiguration(isMeteredAllowed = true) in the updateConfiguration { …​ } block. See the connectivity settings section of Manage onboard regions.

Storage errors on external storage or SD card

Storing the region store on external or removable media works, but needs the right runtime permissions and suffers from FUSE performance penalties on Android 11 and higher. Both pitfalls are described in the filesystem section of Configure map data storage. Wherever possible, keep the region store on internal storage.

IllegalArgumentException: …​ must be an absolute path

All path arguments to buildSdkConfiguration must be absolute paths. Use File(context.filesDir, "…​") or context.getExternalFilesDir(…​); never relative paths.

Online cache exists but no online data is served

• Verify the API key passed to buildSdkConfiguration is valid and has the right entitlements.
• Verify network connectivity from the device — the SDK resumes using online services only when they are actually reachable.
• Check that CacheStorageConfiguration.directoryPath points at a writable directory. A non-writable path causes caching failures.

Where to look in the logs

Inspect logcat around the TomTomSdk.initialize(…​) call to see which configuration was applied and which part of the setup (online cache, region store, keystore) reported a problem.

Next steps