Troubleshooting Mapbox Maps and Navigation SDKs for iOS installation

CocoaPods Installation

If you're already using CocoaPods to manage dependencies in your project, we suggest installing 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 running pod repo update first.
  • When you run pod install, CocoaPods generates an xcworkspace file that includes its configuration. The xcworkspace file has a white Xcode icon, unlike the xcodeproj 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, please 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 Mapbox-iOS-SDK
    curl: (22) The requested URL returned error: 401 Unauthorized
    

    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.

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 Unauthorized
    

    To resolve this, follow the instructions outlined in the installation guide to configure your secret token.

Carthage installation

  • Make sure you're using Carthage version 0.35.0 or above.

  • If you are encountering an error message similar to the one below for any Mapbox framework:

    *** Downloading binary-only framework Mapbox-iOS-SDK at "https://www.mapbox.com/ios-sdk/Mapbox-iOS-SDK.json"
    No available version for binary "https://www.mapbox.com/ios-sdk/MapboxAccounts.json" satisfies the requirement: ~> 2.3.0
    

    You may need to verify that the dependency version specified in your Cartfile is correct, and then reset the Carthage cache:

    rm -rf Carthage &&
    rm -rf ~/Library/Caches/carthage &&
    rm -rf ~/Library/Caches/org.carthage.CarthageKit
    

Mapbox Maps SDK

  • 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 .../mapbox-ios-sdk-dynamic.zip) failed with exit code 9:
    [.../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 .../mapbox-ios-sdk-dynamic.zip or
          .../mapbox-ios-sdk-dynamic.zip.zip, and cannot find .../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

  • If Carthage reports an error similar to this:

    Build Failed
       Task failed with exit code 70:
       /usr/bin/xcrun xcodebuild <...>
    
       This usually indicates that project itself failed to compile. Please check the xcodebuild log for more details: /var/folders/cx/6_wt73h5365_j0ty6085kg2m0000gn/T/carthage-xcodebuild.OahRgR.log
    

    Check that you included the --platform ios key in your carthage 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
    .../mapbox-ios-sdk-dynamic.zip) failed with exit code 9:
    [.../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 .../mapbox-ios-sdk-dynamic.zip or
          .../mapbox-ios-sdk-dynamic.zip.zip, and cannot find .../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.

General Troubleshooting

If your app successfully builds, but you see 401 responses to requests, make sure that you've set your access token correctly. Note that installing Maps SDK v6.0.0 or Navigation SDK v1.0.0 or greater via Carthage or CocoaPods requires two tokens: one to download the SDK and another to authenticate map requests.

Was this page helpful?