Troubleshooting Mapbox Maps and Navigation SDKs for iOS installation
Learn how to troubleshoot issues when installing the Mapbox Maps or Navigation SDK for iOS with Swift Package Manager, CocoaPods, and Carthage.
General troubleshooting
If you see 401
responses after your app builds successfully, make sure that you've configured all credentials correctly. Note that installing Maps SDK v6.0.0, Navigation SDK v1.0.0, or Search SDK v1.0.0 or greater via Carthage or CocoaPods requires two access tokens: one to download the SDK and another to authenticate map requests.
Swift Package Manager
Swift Package Manager (SPM) is the recommended method for installing the Maps SDK. If you run into issues while installing the framework with SPM, try following these steps:
- Xcode may fail to resolve SPM artifacts with errors such as
artifact of binary target 'MapboxCommon' failed extraction: The operation couldn’t be completed. (TSCBasic.StringError error 1.)
. If these errors occur, try resetting the SPM cache by opening the File menu in Xcode and selecting Swift Packages > Reset Package Cache. You may also need to delete your derived data folder.
CocoaPods
Though Swift Package Manager is the preferred method for installing the Maps SDK, if you're already using CocoaPods to manage other dependencies in your project, you can also install the Mapbox SDKs for iOS in the same way.
If you run into issues while installing the framework with CocoaPods, try following these steps:
- Use the most recent version of CocoaPods. Beta versions are not recommended for use with the Mapbox Maps SDK for iOS.
- If
pod install
gives you an “Unable to find a specification” error, try runningpod repo update
first. - When you run
pod install
, CocoaPods generates anxcworkspace
file that includes its configuration. Thexcworkspace
file has a white Xcode icon, unlike thexcodeproj
file which has a blue Xcode icon. Make sure you're opening this file and not the original Xcode project. - If you're getting a permission error or having trouble installing CocoaPods itself, consult the CocoaPods troubleshooting documentation.
If you're still having issues using Mapbox with CocoaPods, contact support with the complete details of the issue, including error messages.
Mapbox Maps SDK
-
If you see the error
Mapbox.h not found
, this can typically be resolved by building your application despite the error. -
If you're using version v6.0.0 of the SDK or later, you will need to authorize your download of the Maps SDK with a secret access token with the
DOWNLOADS:READ
scope. Otherwise, you will see the following error:[!] Error installing MapboxMaps
curl: (22) The requested URL returned error: 401 UnauthorizedTo resolve this, create a secret access token from your Mapbox account and follow the instructions outlined in the installation guide to configure your secret token.
Mapbox Navigation SDK
-
If you're using version v1.0.0 of the SDK or later, you will need to authorize your download of the Navigation SDK with a secret access token with the
DOWNLOADS:READ
scope. Otherwise, you will see the following error:[!] Error installing MapboxNavigation
curl: (22) The requested URL returned error: 401 UnauthorizedTo resolve this, create a secret access token from your Mapbox account and follow the instructions outlined in the installation guide to configure your secret token.
Carthage
Mapbox Maps SDK
v10.0.0 and higher
Installation via Carthage is not supported in the Maps SDK for iOS v10.0.0 and higher.
Less than v10.0.0
If you run into issues while installing the framework with Carthage, try following these steps:
-
Make sure you're using Carthage version 0.35.0 or above.
-
If you are encountering an error message like the one below for any Mapbox framework:
*** Downloading binary-only framework MapboxMaps at "https://api.mapbox.com/downloads/v2/mobile-maps-ios/releases/ios/{VERSION_NUMBER}/MapboxMaps.zip"
No available version for binary "https://s3.amazonaws.com/mapbox-ios/accounts/MapboxAccounts.json" satisfies the requirement: ~> 2.3.0You may need to verify that the dependency version specified in your
Cartfile
is correct, and then reset theCarthage
cache:rm -rf Carthage &&
rm -rf ~/Library/Caches/carthage &&
rm -rf ~/Library/Caches/org.carthage.CarthageKit
-
If you're using version v6.0.0 of the SDK or later, you will need to authorize your download of the Maps SDK with a secret access token with the
DOWNLOADS:READ
scope. Otherwise, you will see the following error:A shell task (/usr/bin/env unzip -uo -qq -d .@site/src/mapbox-ios-sdk-dynamic.zip) failed with exit code 9:
[.@site/src/mapbox-ios-sdk-dynamic.zip]
End-of-central-directory signature not found. Either this file is not
a zipfile, or it constitutes one disk of a multi-part archive. In the
latter case the central directory and zipfile comment will be found on
the last disk(s) of this archive.
unzip: cannot find zipfile directory in one of .@site/src/mapbox-ios-sdk-dynamic.zip or
.@site/src/mapbox-ios-sdk-dynamic.zip.zip, and cannot find .@site/src/mapbox-ios-sdk-dynamic.zip.ZIP, period.To resolve this, create a secret access token from your Mapbox account and follow the instructions outlined in the installation guide to configure your secret token.
-
If you continue to run into the same error after including your
~/.netrc
file, try resetting your Carthage cache and try installing again. See cache resetting instructions above.
Mapbox Navigation SDK
v2.0.0 and higher
MapboxNavigation
no longer supports Carthage as of v2.0.0. If you are building a user interface from scratch, you can still install only the MapboxCoreNavigation
framework using Carthage.
Less than v2.0.0
-
If
Carthage
reports an error like this:Build Failed
Task failed with exit code 70:
/usr/bin/xcrun xcodebuild <...>
This usually indicates that project itself failed to compile. Check the xcodebuild log for more details: /var/folders/cx/6_wt73h5365_j0ty6085kg2m0000gn/T/carthage-xcodebuild.OahRgR.logCheck that you included the
--platform ios
key in yourcarthage update
command:% carthage update --platform ios --use-netrc
-
If you are using version v1.0.0 of the SDK or later, you will need to authorize your download of the Navigation SDK with a secret access token with the
DOWNLOADS:READ
scope. Otherwise, you will see the following error:A shell task (/usr/bin/env unzip -uo -qq -d
.@site/src/mapbox-ios-sdk-dynamic.zip) failed with exit code 9:
[.@site/src/mapbox-ios-sdk-dynamic.zip]
End-of-central-directory signature not found. Either this file is not
a zipfile, or it constitutes one disk of a multi-part archive. In the
latter case the central directory and zipfile comment will be found on
the last disk(s) of this archive.
unzip: cannot find zipfile directory in one of .@site/src/mapbox-ios-sdk-dynamic.zip or
.@site/src/mapbox-ios-sdk-dynamic.zip.zip, and cannot find .@site/src/mapbox-ios-sdk-dynamic.zip.ZIP, period.To resolve this, follow the instructions outlined in the installation guide to configure your secret token.
-
If you continue to run into the same error after including your
~/.netrc
file, try resetting your Carthage cache and try installing again. See cache resetting instructions above.
CI troubleshooting
If you use a dependency manager and automate builds on CI, you need to update your CI configuration. Below are the instructions to integrate the .netrc
file into your CI:
- A secret access token with the
Downloads:Read
scope.- From your account's tokens page, click the Create a token button.
- From the token creation page, give your token a name and make sure the box next to the
Downloads:Read
scope is checked. - Click the Create token button at the bottom of the page to create your token.
- The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.
- Add an
SDK_REGISTRY_TOKEN
environment variable to your CI system of choice. - In your CI configuration file (or in a Script step), insert a new run step before fetching dependencies to the build job which runs the following commands:
echo "machine api.mapbox.com
login mapbox
password ${SDK_REGISTRY_TOKEN}" >
~/.netrc - If the project uses Carthage, change the carthage bootstrap invocation to pass in
--use-netrc
. Add this flag to the Additional Options field of the Carthage step. - Note that the secret access token in the
~/.netrc
file is sensitive and should not be exposed in any public CI logs. Refer to your continuous integration provider’s documentation on how to keep your secret access token from appearing in public logs.