Troubleshooting

Just as troubleshooting is a part of every complex technical process, it’s a necessary part of developing, testing, submitting, and releasing an app. The potential problems you may encounter are organized here in four general areas—certificates, provisioning, building, and debugging—with each problem followed by specific advice. Use this chapter as a reference to find solutions to problems you might encounter.

Certificate Issues

Before you re-create a certificate that has become invalid or unusable, see whether it has one or more of the following common problems.

You’re Missing Signing Identities or Code-Signing Certificate

Xcode detects when you’re missing a signing identity, as needed, depending on the operation you’re performing. For example, if you attempt to run an app on a iOS device, a dialog may appear asking if Xcode should request a missing development certificate. If this happens, click Fix Issue or Request in the dialog that appears.

If the certificate already exists in Member Center, a “Your account already has a valid certificate” dialog appears. Typically, this happens when you move from one Mac to another. If possible, export your certificates as a developer profile file on the other Mac, and then import them on your new Mac, as described in “Exporting and Importing Certificates and Profiles.” If you don’t have a backup of your developer profile, click the “Revoke and Request” button when the “Your account already has a valid certificate” dialog appears.

You can also request specific types of certificates, as described in “Requesting Signing Identities.”

No Matching Signing Identity or Provisioning Profiles Found

If a warning message and Fix Issue button appear below the Team pop-up menu in the General pane or in a section of the Capabilities pane in the project editor, read the message and click the Fix Issue button. Xcode may present a series of dialogs asking for more information. For example, a dialog might ask you to select a team for your project, request your development certificate, or register a device. Xcode needs these assets to create your team provisioning profile. If Xcode doesn’t resolve the issue, first follow all the steps in “Configuring Identity and Team Settings” to verify your project configuration.

For iOS apps, connect a device you want to use for development to your Mac and choose it from the Scheme toolbar menu before clicking Fix Issue. (Xcode automatically registers connected devices selected from this menu.) If the device doesn’t appear in the menu, enable it for development, as described in “Registering Devices Using Xcode.”

Read “The Private Key for Your Signing Identity Is Missing” if you’re missing a private key in your keychain.

The Private Key for Your Signing Identity Is Missing

Code signing fails if the private key for your signing identity isn’t in your keychain.

If the private key for your development certificate is missing, Xcode displays a warning message and several options to fix the issue below the Team pop-up menu in the General pane in the project editor. If you created a backup of your signing identities on this or another Mac, as described in “Exporting Your Developer Profile,” click the Import Developer Profile button to restore the private key in your keychain. Otherwise, click the “Revoke and Request” button to create a new signing identity. Remove the signing identity with the missing private key from you keychain, as described in “Removing Signing Identities from Your Keychain.”

If you use a custom development provisioning profile that you manage yourself, it becomes invalid after revoking the development certificate. Read “Editing Provisioning Profiles in Member Center” to regenerate it.

If the private key for a distribution certificate is missing, try to restore it from a developer profile backup, as described in “Importing Your Developer Profile.” If you can’t retrieve your private keys from another Mac, refer to “Re-Creating Certificates and Updating Related Provisioning Profiles” to re-create these types of certificates. You can perform these steps for one or more certificates.

The Private Key for a Developer ID Certificate Is Missing

Follow the same steps in “The Private Key for Your Signing Identity Is Missing” to repair Developer ID certificates, except contact Apple at product-security@apple.com if you need to revoke Developer ID certificates. Alternatively, you can continue to develop and distribute applications by requesting additional Developer ID certificates, as described in “Requesting Additional Developer ID Certificates.”

Your Certificates Are Invalid Because You’re Missing an Intermediate Certificate

If your certificates are invalid, you could be missing the intermediate certificate used to authenticate your certificate. If you verify your certificate in Keychain Access, as described in “Verifying Using Keychain Access,” and instead of a green circle with a checkmark, a red circle with a white X appears with the status “This certificate was signed by an unknown authority,” you’re missing the intermediate certificate. If you don’t have a certificate called Apple Worldwide Developer Relations Certification Authority in your system keychain, read “Installing Missing Intermediate Certificate Authorities” to learn how to reinstall it. The intermediate certificate for Developer ID certificates is called the Developer ID Certification Authority.

Your Certificates Have Trust Issues

If you view your certificate in Keychain Access, and a blue circle and white plus sign appear in the detail area instead of a green circle with a checkmark, your certificate has trust issues. To learn how to fix this problem, read “Xcode Doesn’t Trust Your Certificate.”

Your Provisioning Profile or Signing Identity Doesn’t Appear in Xcode Menus

Occasionally, your provisioning profile or signing identity doesn’t appear in a Provisioning Profile or Signing Identity pop-up menu when distributing your app using the Devices organizer or when setting the Code Signing Identity build setting in the project editor. When this occurs, refresh provisioning profiles in Xcode, as described in “Refreshing Provisioning Profiles in Xcode.”

If your provisioning profile still doesn’t appear in the Code Signing Identity build setting menu, choose Don’t Code Sign or a certificate under Automatic Profile Selector from the Code Signing Identity menu. The next time you choose the Code Signing Identity menu, your provisioning profile should appear in the menu.

Duplicate Signing Identities or Provisioning Profiles Appear in Accounts Preferences

The view details dialog in Accounts preferences displays signing identities that are in your keychain, not certificates in Member Center. You can have multiple accounts and belong to different teams, but you should have only one of each type of certificate for each team. For a list of the certificate types, refer to Table 11-2. If duplicate signing identities appear, you can remove the expired or revoked signing identities from your keychain, as described in “Removing Signing Identities from Your Keychain.”

If duplicate provisioning profiles appear in the view details dialog in Accounts preferences, refresh provisioning profiles in Xcode, as described in “Refreshing Provisioning Profiles in Xcode.”

Your Certificates Have Expired

You can’t renew expired certificates. Read “Replacing Expired Certificates” for how to remove the expired certificates and request new ones.

Your Request Has Timed Out

If a dialog appears stating that your request has timed out, the Certificates, Identifiers & Profiles section of Member Center is probably down for maintenance. To see whether you have access to Certificates, Identifiers & Profiles, sign in to Member Center using the same Apple ID credentials you entered in Xcode. In Certificates, Identifiers & Profiles, select Certificates or Provisioning Profiles. If you can view your assets, Certificates, Identifiers & Profiles is not down.

Provisioning Issues

Common provisioning issues result from using the wrong provisioning profile with your app or using an invalid or expired provisioning profile.

Provisioning Profiles Installed on Your Device Are Invalid

If the provisioning profile on your development device has expired or is invalid, remove it as described in “Removing Provisioning Profiles from Devices.”

Provisioning Profiles Appear Invalid in Member Center

If a team provisioning profile appears invalid in Member Center, refresh provisioning profiles in Xcode, as described in “Refreshing Provisioning Profiles in Xcode.”

If a provisioning profile you manage appears invalid in Member Center, remove or edit it, as described in “Removing Provisioning Profiles from Member Center” and “Editing Provisioning Profiles in Member Center.”

No Such Provisioning Profile Was Found

If a “Your build settings specify a provisioning profile with […] however, no such provisioning profile was found.” warning message appears below the Team pop-up menu in the General pane, you may have incorrect Provisioning Profile and Code Signing Identity build settings from using an earlier version of Xcode.

When this occurs, click the Fix Issue button below the warning message. If necessary, click the Fix Issue button again. The Provisioning Profile build setting should be None and the Code Signing Identity build setting should be Automatic > iOS Developer for iOS apps, and Automatic > Mac Developer for Mac apps.

If you’re using a custom development provisioning profile, read “Setting the Code Signing Identity Build Setting” for how to configure your project.

Build and Code Signing Issues

If you use the team provisioning profile that Xcode manages for you during development, as described in “Team Provisioning Profiles in Depth,” Xcode fixes code signing and provisioning issues for you before you attempt to build your app. In this case, you shouldn’t set the Code Signing Identity build settings yourself. However, if you want to use a custom development provisioning profile and set these build settings, as described in “Setting the Code Signing Identity Build Setting,” you may encounter build issues described in this section. Common build errors tend to involve incorrect code signing identities.

Xcode Can’t Find Your Provisioning Profile

You’ll receive the following error message after replacing a provisioning profile with a modified version, such as when a provisioning profile’s App ID changes:

Code Sign error: Provisioning Profile 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx' can’t be found

To address this error, ensure that the correct provisioning profile and code signing identity are selected for the value of the Code Signing Identity build setting. This error may also occur if the project’s and target’s Code Signing Identity build settings are different.

Xcode Doesn’t Trust Your Certificate

You get this error message when Xcode can’t verify the authenticity of your development or distribution certificate:

Code Sign error: CSSMERR_TP_NOT_TRUSTED

If the trust setting isn’t Use System Defaults, you’ll receive a CSSMERR_TP_TRUSTED error message from the codesign command-line utility when you build and run your app. Don’t change the trust settings of your certificates from the default Use System Defaults. Follow these steps to repair your development, distribution, and intermediate certificates.

bullet
To set the trust level of a certificate to the system defaults
  1. Launch Keychain Access.

  2. In the Category section, select My Certificates.

  3. Double-click the certificate.

  4. In the certificate window, display the Trust section by clicking the corresponding disclosure triangle.

  5. For the option “When using this certificate,” select Use System Defaults.

  6. Close the certificate window.

  7. Ensure that the certificate information shows the certificate is valid.

The Code Signing Identity Build Setting Doesn’t Match Any Certificates

You’ll receive the following error message when your certificate has expired or is otherwise invalid:

Code Signing Identity 'iPhone Developer' doesn't match any valid, non-expired, certificate/private key pair in your keychain.

For multiple targets that use the same code signing identity, you should set this build setting at the project level, not the target. However, if it’s set on both the project and the target, the target setting overrides the project setting. If the target’s Code Signing Identity build setting is set, delete it by first selecting it and then choosing Edit > Delete. Finally, set the project’s Code Signing Identity build setting to your certificate.

If your development certificate or team provisioning profile doesn’t appear in the Code Signing Identity menu, try refreshing the provisioning profiles, as described in “Refreshing Provisioning Profiles in Xcode,” and choose a valid code signing identity, as described in “Setting the Code Signing Identity Build Setting.”

Your Keychain Contains Duplicate Code Signing Identities

You get one of these error messages when there are duplicate code signing identities in your keychain, such as two development identities or two distribution identities (your keychain must contain at most one code signing identity of each type):

Build error "iPhone Developer: <your_name> (XYZ123ABC): ambiguous (matches "iPhone Developer: <your_name> (XYZ123ABC)" in /Library/Keychains/System.keychain and "iPhone Developer: <your_name> (XYZ123ABC)" in /Users/../Library/Keychains/login.keychain)"

[BEROR]CodeSign error: Certificate identity 'iPhone Distribution: <your_name>' appears more than once in the keychain. The codesign tool requires there only be one.

To address these errors, try deleting the duplicate code signing identities from your keychain, as described in “Removing Signing Identities from Your Keychain.”

The App ID in Your Provisioning Profile Doesn’t Match Your App’s Bundle Identifier

When there’s a conflict between the App ID in the provisioning profile selected in the Code Signing Identity build setting and your app’s bundle identifier, you get error messages similar to the following:

Code Sign error: Provisioning profile 'MyApp Profile' specifies the Application Identifier 'com.mycompany.MyApp.*' which doesn't match the current setting 'com.mycompany.MyApp'

To address these errors, ensure that your bundle identifier is set correctly in your Xcode project, that the certificate and provisioning profile specified in the Code Signing Identity build setting is correct, and that the provisioning profile uses the correct App ID.

Your iOS Device Isn’t Listed as a Run Destination

If you have a project or workspace open and your connected device isn’t listed as a run destination in the Scheme pop-up menu, verify that:

  1. Your device is enabled for development.

    Read “Registering Devices Using Xcode” for how to enable a device for development.

  2. Your device contains a valid provisioning profile.

  3. The app’s targeted iOS version is equal to or greater than the iOS version installed on your device.

    See “Setting the Target iOS Devices” for details.

  4. The version number of the iOS SDK your project uses is equal to or greater than the version number of the iOS version on your device.

    For example, if Xcode shows iOS SDK 4.3 but your device has iOS 5.0 installed, you need to install on your Mac an Xcode version that includes iOS SDK 5.0.

Debugging Information Issue

The most common potential problem with debugging is that Xcode hasn’t yet collected the information from your device.

Xcode Displays the Unknown iOS Detected Dialog When You Connect a Device

This message appears when Xcode hasn’t seen a particular version of iOS before and needs to download (from the device) the debugging symbols for that version from the device. To successfully debug apps on the device, leave the device connected until Xcode finishes downloading the debugging symbols from the device.