[Bug]: Offline Map not visible

[Alessandro-v]

Mapbox Navigation SDK version

3.25.1

Steps to reproduce

Hi,
I'm implementing Mapbox in my app, and since some routes need to work offline, I'm implementing offline navigation. The user can download routes from a list of GPX files that belong to a travel itinerary. After downloading the selected route and its offline map data, the user should be able to display the route and start navigation without an internet connection. However, I'm encountering an error when displaying a route and starting navigation while offline.

Here's the download code:

func downloadRegion(
        region: OfflineRegion,
        downloadingRegions: Set<String>,
        onDownloadingRegionsUpdate: @escaping (Set<String>) -> Void,
        onProgress: @escaping (String, Float) -> Void,
        onCompletion: @escaping (String, Result<TileRegion, Error>) -> Void
    ) {
        guard !downloadingRegions.contains(region.id) else {
            return
        }
        
        let tileStore = TileStore.default
        let offlineManager = OfflineManager()
        
        let tilesetDescriptor = offlineManager.createTilesetDescriptor(
            for: TilesetDescriptorOptions(
                styleURI: .streets,
                zoomRange: 6...16,
                tilesets: [
                    "mapbox://mapbox.mapbox-streets-v8",
                ]
            )
        )
        
        let loadOptions = TileRegionLoadOptions(
            geometry: region.geometry,
            descriptors: [tilesetDescriptor],
            metadata: nil,
            acceptExpired: true,
            networkRestriction: .none
        )!
        
        var updatedDownloadingRegions = downloadingRegions
        updatedDownloadingRegions.insert(region.id)
        onDownloadingRegionsUpdate(updatedDownloadingRegions)
        onProgress(region.id, 0.0)
        
        let _ = tileStore.loadTileRegion(
            forId: region.id,
            loadOptions: loadOptions
        ) { progress in
            let totalResources = max(progress.requiredResourceCount, 1)
            let progressValue = Float(progress.completedResourceCount) / Float(totalResources)
            onProgress(region.id, progressValue)
        } completion: { result in
            updatedDownloadingRegions.remove(region.id)
            onDownloadingRegionsUpdate(updatedDownloadingRegions)
            onCompletion(region.id, result)
        }
    }

The safety data check performed after the download confirms that the region has been stored.

private func downloadDataCheck() {
        let tileStore = TileStore.default
        tileStore.tileRegion(forId: regionID) { result in
            DispatchQueue.main.async {
                switch result {
                case .success(let tileRegion):
                    self.isDownloaded = true
                    debugPrint("MB \(Double(tileRegion.completedResourceSize) / (1024 * 1024))")
                case .failure(_):
                    self.isDownloaded = false
                    onDownloadedChange?(false, 0.0)
                }
            }
        }
    }

Expected behavior

After the offline region download completes, I expect the downloaded area to be displayed when I open the map. Instead, I only see an empty world, and even if I zoom into the downloaded area, no map content is rendered.

I'm not sure if I'm missing an initialization step or if the map needs to be displayed at least once while online before the offline tiles can be rendered correctly. In fact, if I open the map once with network connectivity, the downloaded area is then displayed correctly in offline mode as well.

Actual behavior

As I mentioned earlier, when I open the map, only a blank globe is displayed, and I see several errors in the console.

[Warning, tile_store]: Option allow-in-memory-download is not recognized and will be ignored.

Task <6F24D1BF-28F7-4DA6-9F0A-B78605202458>.<730> finished with error [-1009] Error Domain=NSURLErrorDomain Code=-1009 "The Internet connection appears to be offline." UserInfo={_kCFStreamErrorCodeKey=50, NSUnderlyingError=0x11f95dce0 {Error Domain=kCFErrorDomainCFNetwork Code=-1009 "(null)" UserInfo={_kCFStreamErrorDomainKey=1, _kCFStreamErrorCodeKey=50, _NSURLErrorNWResolutionReportKey=Resolved 0 endpoints in 1ms using unknown from cache, _NSURLErrorNWPathKey=unsatisfied (No network route)}}, _NSURLErrorFailingURLSessionTaskErrorKey=LocalDataTask <6F24D1BF-28F7-4DA6-9F0A-B78605202458>.<730>, _NSURLErrorRelatedURLSessionTaskErrorKey=(
    "LocalDataTask <6F24D1BF-28F7-4DA6-9F0A-B78605202458>.<730>"
), NSLocalizedDescription=The Internet connection appears to be offline., NSErrorFailingURLStringKey=https://api.mapbox.com/route-tiles/v2/mapbox/driving-traffic/versions?access_token=******&sku=*****, NSErrorFailingURLKey=https://api.mapbox.com/route-tiles/v2/mapbox/driving-traffic/versions?access_token=****&sku=***, _kCFStreamErrorDomainKey=1}

[Error, nav-native]: Unable to find the latest version of routing tiles!
[Error, nav-native]: Async config init - Unable to determine the tiles version
[Warning, maps-core]: The outdated resource mapbox://styles/mapbox/standard shall be updated explicitly using Offline API
[Warning, maps-core/style]: Repeated slot 'middle', ignoring

Let me know If u need more info.
Thanks in advance.

Is this a one-time issue or a repeatable issue?

repeatable

[ArtemStepuk]

Hello and thanks you for the detailed report.

This looks like a missing piece in the offline download flow. Offline map + navigation needs three downloads, and the style URI must match what the map actually loads.

Please take a look on the flow in our Examples project: Offline-Regions.swift:

• loadStylePack — downloads style JSON, sprites, glyphs, etc. Without this, a cold offline start often shows a blank globe.
• loadTileRegion — downloads map tiles for that same style URI (via a maps tileset descriptor).
• getLatestNavigationTilesetDescriptor() — include this in TileRegionLoadOptions.descriptors so routing tiles are packed as well (this addresses the Unable to find the latest version of routing tiles errors).

Opening the map once online works because resources are cached ambiently; that is not a substitute for a proper style pack + matching tile region.

Docs: Manage offline data