nav-ios 3.24.2 Package.swift target '_MapboxNavigationTestKit' references non-existent path 'Sources/.empty/_MapboxNavigationTestKit' — breaks SPM resolution

[critchha]

Environment

• Xcode version: 26.5 (Build 17F42)
• iOS version: N/A — fails at SPM dependency resolution, never reaches a runtime. App deployment target is iOS 18.0.
• Devices affected: All targets. Build-time failure on iOS Simulator (arm64 and x86_64) and on-device builds (arm64).
  The defect is in the package manifest itself, so it's platform-independent.
• Maps SDK Version:
  • mapbox-navigation-ios 3.24.2 ← failing package
  • mapbox-maps-ios 11.24.2
  • mapbox-navigation-native-ios 324.24.2
  • MapboxCommon 24.24.2
  • MapboxSearch 2.24.2

Observed behavior and steps to reproduce

The mapbox-navigation-ios v3.24.2 Package.swift declares the _MapboxNavigationTestKit target with a path: that does
not exist in the source tree:

.target(
name: "_MapboxNavigationTestKit",
dependencies: [
.product(name: "SnapshotTesting", package: "swift-snapshot-testing"),
"_MapboxNavigationTestHelpers",
],
path: "Sources/.empty/_MapboxNavigationTestKit"
),

The directory Sources/.empty/ does not exist in the v3.24.2 source tree. Confirmed via:

$ ls SourcePackages/checkouts/mapbox-navigation-ios/Sources/
_MapboxNavigationHelpers
_MapboxNavigationLocalization
_MapboxNavigationTestHelpers
CarPlayTestHelper
MapboxDirections
MapboxDirectionsCLI
MapboxNavigationCore
MapboxNavigationUIKit
TestHelper

SwiftPM rejects this with:

xcodebuild: error: Could not resolve package dependencies:
Couldn't fetch updates from remote repositories:
invalid custom path 'Sources/.empty/_MapboxNavigationTestKit' for target '_MapboxNavigationTestKit'

The error appears every time swift package resolve or xcodebuild -resolvePackageDependencies is invoked against a
clean DerivedData / SPM artifacts state. Once resolution fails, downstream xcframework artifacts (Turf,
MapboxCoreMaps, MapboxCommon, MapboxCoreSearch, MapboxNavigationNative) are never downloaded, and subsequent build
attempts produce cascading error: There is no XCFramework found at …Turf.xcframework errors across every dependent
target.

Reproduce

1. Create an iOS project pinning mapbox-navigation-ios to exactVersion: 3.24.2 via SPM (which transitively pulls
   mapbox-maps-ios 11.24.2, mapbox-navigation-native-ios 324.24.2, etc.).
2. Clean DerivedData and the local SwiftPM caches:
   rm -rf ~/Library/Developer/Xcode/DerivedData/{Project}-*
   ~/Library/Caches/org.swift.swiftpm/repositories/mapbox-*
3. Resolve packages:
   xcodebuild -resolvePackageDependencies -scheme {Scheme}
4. Observe: resolution fails with the invalid custom path 'Sources/.empty/_MapboxNavigationTestKit' error quoted
   above.

Reproduces reliably across at least one full session (Xcode 26.5). Intermittently a "lucky" resolve appears to succeed
if the SPM caches have a partial prior state, but a subsequent build phase still references the missing path and
re-triggers the failure.

Expected behavior

Either:

1. The Sources/.empty/_MapboxNavigationTestKit directory exists in the v3.24.2 source tree (with at least a
   placeholder source file, since SwiftPM does not accept truly empty target directories without a corresponding marker),
   or
2. The _MapboxNavigationTestKit target is removed from Package.swift at release time if it has no associated sources,
   or
3. The target's path: is updated to point at the actual source location.

In any case, xcodebuild -resolvePackageDependencies against a clean cache should succeed for v3.24.2, as it did for
v3.23.x.

Notes / preliminary analysis

• The previous published release, v3.24.1, does not appear to have this defect; bumping back to 3.24.1 / 11.24.1 /
  2.24.1 resolves cleanly (though 11.24.1 has its own separate umbrella-header packaging defect filed as MapboxNavigationNative 324.24.1: private umbrella header omits three shipped PrivateHeaders/ files, breaks Xcode 16 explicit-module precompile #4828 —
  distinct from this report).
• The previous LTS-style line v3.23.0 / 11.23.0 / 2.23.0 also resolves cleanly.
• The .empty/ directory convention suggests this target may have been a placeholder intentionally left empty in source
  but expected to be materialized by Mapbox's release-prep tooling — and that tooling appears to have not run for the
  3.24.2 cut.
• Same family of issue as mapbox-navigation-ios#4799 ("Invalid Package.swift manifest of mapbox-navigation-native-ios
  in latest release") — also an invalid custom path defect from omitted release-time source population. [Bug]: Invalid Package.swift manifest of mapbox-navigation-native-ios in latest release #4799 was
  reportedly fixed on main but the fix did not propagate to all release-cut paths.
• This release line also has a separate packaging defect in MapboxNavigationNative.framework's private umbrella header
  (filed as mapbox-navigation-ios#4828) — the umbrella omits three #import lines for headers it physically ships in
  PrivateHeaders/. Even if the TestKit path defect in this report is fixed, the umbrella defect in MapboxNavigationNative 324.24.1: private umbrella header omits three shipped PrivateHeaders/ files, breaks Xcode 16 explicit-module precompile #4828 would still
  block adoption of 3.24.2 without an additional fix.

A patch script targeting the umbrella header alone (scripts/patch-mapbox-umbrella.sh in our app's repo, idempotent,
marker-guarded, applied as a pre-build phase) successfully bypasses #4828 in cached-resolve states. However, it cannot
bypass the TestKit defect in this report — SwiftPM never reaches the dependency-extraction stage when the manifest
itself is invalid. Both #4828 and this report need to be fixed upstream for the 11.24 line to be adoptable.

Additional links and references

• Failing tag: https://github.com/mapbox/mapbox-navigation-ios/releases/tag/v3.24.2
• Failing manifest: https://github.com/mapbox/mapbox-navigation-ios/blob/v3.24.2/Package.swift (see target declaration
  for _MapboxNavigationTestKit)
• Related: [Bug]: Invalid Package.swift manifest of mapbox-navigation-native-ios in latest release #4799 (closed, same class of defect)
• Related: MapboxNavigationNative 324.24.1: private umbrella header omits three shipped PrivateHeaders/ files, breaks Xcode 16 explicit-module precompile #4828 (open, distinct defect in the same 11.24
  release line)

[ArtemStepuk]

Hello, we've tried to reproduce the issue with the similar environment but no luck. Could you please double-check that the correct products are added to the app target (get started ref). It should be:

• MapboxNavigationCore
• MapboxNavigationUIKit

thank you!

[critchha]

Thanks — tried it. We dropped the direct mapbox-maps-ios SPM dependency and the explicit MapboxMaps product on the
app target. MapboxMaps now resolves transitively via nav-ios (still pulls 11.24.2 thanks to nav-ios's exact pin), and we still import MapboxMaps / import MapboxDirections from app code without issues. Resolve + iOS Simulator build both succeed clean.
Caveat: the _MapboxNavigationTestKit path error was intermittent for us, so a clean resolve in this config isn't proof it's fixed — only that the recommended setup builds. We'll keep an eye on it as we cut more builds. If your team can confirm whether the direct mapbox-maps-ios reference is unsupported (vs. just discouraged) for nav-ios consumers, that'd help us write our config story down.