Map corruption recovery

An onboard NDS map or its associated keystore file can occasionally become corrupted. This could be due to a variety of reasons, namely a storage failure, an interrupted write, or an unexpected device shutdown. When this happens, the SDK detects the problem and notifies your application so you can recover without crashing.

This guide explains what failures can occur, how to listen for them, and how to replace the map or keystore to restore normal operation.

Understanding recoverable failures

When the SDK detects a problem with the onboard map or keystore it emits one of the following recoverable failures as a TomTomSdkFailure, each carrying the RegionStore reference you use for recovery.

Failures can be reported both during initialization and at runtime while the store is in use.

Listening for failures

Collect from the TomTomSdk.failures flow to be notified when the SDK detects a problem:

1
lifecycleScope.launch {
2
    TomTomSdk.failures.collect { failure ->
3
        when (failure) {
4
            is TomTomSdkFailure.CannotReadMap -> recoverMap(failure.regionStore)
5
            is TomTomSdkFailure.CannotReadKeyStore -> recoverKeystore(failure.regionStore)
6
        }
7
    }
8
}

The recoverMap and recoverKeystore helper functions are implemented in the sections below.

Replacing the map

Call replaceMap() to overwrite the current onboard map with a known-good map. The operation runs on a background thread and reports progress and completion through its callback.

Expected directory structure

The newMapDirectoryPath parameter must point to the DATA directory of the backup map, the directory that directly contains the map’s database files, including ROOT.NDS. The typical on-disk layout of a backup map looks like this:

1
backup-map/
2
└── DATA/          <-- pass this path as newMapDirectoryPath
3
    ├── ROOT.NDS
4
    └── ...

Preparing the backup map from app assets

A common pattern is to bundle a known-good (empty) map as a zip file in your app’s assets and extract it to internal storage on first launch. The following helpers extract the zip to internal storage and return the DATA directory path ready to pass to replaceMap():

1
private fun extractBackupMap(): File {
2
    val outputDir = File(context.filesDir, "backup-map")
3
    if (!outputDir.exists()) {
4
        extractZipToDir("backup-map.zip", outputDir)
5
    }
6
    return File(outputDir, "DATA")
7
}
8

9
private fun extractZipToDir(
10
    assetName: String,
11
    outputDir: File,
12
) {
13
    context.assets.open(assetName).use { input ->
14
        ZipInputStream(input).use { zip ->
15
            generateSequence { zip.nextEntry }.forEach { entry ->
16
                extractZipEntry(zip, entry, outputDir)
17
            }
18
        }
19
    }
20
}
21

22
private fun extractZipEntry(
23
    zip: ZipInputStream,
24
    entry: ZipEntry,
25
    outputDir: File,
26
) {
27
    val outFile = File(outputDir, entry.name)
28
    if (entry.isDirectory) {
29
        outFile.mkdirs()
30
    } else {
31
        outFile.parentFile?.mkdirs()
32
        outFile.outputStream().use { zip.copyTo(it) }
33
    }
34
}

Calling replaceMap

1
@Suppress("UNUSED_ANONYMOUS_PARAMETER")
2
private fun recoverMap(regionStore: RegionStore) {
3
    val backupDataDir = extractBackupMap() // points to the DATA directory
4
    regionStore.replaceMap(
5
        newMapDirectoryPath = backupDataDir,
6
        newMapFileList = null, // null copies all files without checksum validation
7
        callback = object : Callback<Unit, MapUpdateError> {
8
            override fun onSuccess(result: Unit) {
9
                // Map replaced successfully; normal operation resumes.
10
            }
11

12
            override fun onFailure(failure: MapUpdateError) {
13
                // Replacement failed. The store has no valid map.
14
                // Call replaceMap() again with correct parameters to recover.
15
            }
16
        },
17
        progressReporter = { progress ->
18
            // progress is 0–100
19
        },
20
    )
21
}

The newMapFileList parameter accepts a list of NewMapFile entries with per-file checksums. When provided, each file is validated before being written. If any file fails validation, MapUpdateError.FileValidationError is reported and no partial map is left behind.

Replacing the keystore

Call replaceKeystore() to overwrite the existing keystore file with a valid one. The new file must be readable from the path you provide.

1
private fun recoverKeystore(regionStore: RegionStore) {
2
    regionStore.replaceKeystore(
3
        newKeystoreFilePath = File("/path/to/backup/keystore.sqlite"),
4
        keystoreChecksum = "", // pass a non-empty string to validate before writing
5
        callback = object : Callback<Unit, MapUpdateError> {
6
            override fun onSuccess(result: Unit) {
7
                // Keystore replaced successfully.
8
            }
9

10
            override fun onFailure(failure: MapUpdateError) {
11
                // Replacement failed. Check that the source file exists and is readable.
12
            }
13
        },
14
    )
15
}

Pass a non-empty keystoreChecksum to validate the replacement file before it is written. If the checksum does not match, MapUpdateError.FileValidationError is reported and the existing keystore is left unchanged.

Concurrent recovery calls

Only one recovery operation, either replaceMap() or replaceKeystore(), can be in progress at a time. If you call either method while a recovery is already running, the callback immediately receives MapUpdateError indicating the operation is already in progress. Wait for the in-progress operation to complete before retrying.

If a new error is detected while a recovery is already in progress — for example, a keystore error occurring during a map replacement — the SDK defers it and delivers it once the current recovery finishes, through the same channel you receive failures on. Your handler must therefore be prepared to be called again immediately after a recovery completes, potentially with a different failure type requiring a second recovery step.

Enabling updates before recovery

Map updates must be enabled on the RegionStore before calling replaceMap() or replaceKeystore(). If updates are disabled at the time of the call, an error is reported. Enable updates before initiating recovery:

1
regionStore.setUpdatesEnabled(true)

1
val failureListener = object : NdsStoreFailureListener {
2
    override fun onFailure(
3
        ndsStore: NdsStore,
4
        ndsStoreRecoverableFailure: NdsStoreRecoverableFailure,
5
    ) {
6
        when (ndsStoreRecoverableFailure) {
7
            is NdsStoreRecoverableFailure.MissingMap,
8
            is NdsStoreRecoverableFailure.CannotReadMap,
9
            -> recoverMap(ndsStore)
10
            is NdsStoreRecoverableFailure.CannotReadKeyStore -> recoverKeystore(ndsStore)
11
        }
12
    }
13
}
14

15
ndsStore = NdsStore(
16
    context = context,
17
    ndsStorePath = File("/path/to/nds/map"),
18
    apiKey = "YOUR_API_KEY",
19
    failureListener = failureListener,
20
)