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 an 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 appears in the ineligible list in the menu, read Your iOS Device Isn’t Listed or Is Ineligible in the Scheme Toolbar Menu.

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 your 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 a pop-up menu when distributing your app using the Devices window 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 choose a certificate under Automatic Profile Selector from the Code Signing Identity pop-up menu. The next time you use the Code Signing Identity pop-up 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 13-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. For example, if you enable push notifications for an App ID using Member Center, use Xcode to regenerate the associated team provisioning profiles.

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. A provisioning profile is invalid if it contains a revoked or expired certificate. A provisioning profile is also invalid if its App ID entitlements change or its App ID is deleted. A development or ad hoc provisioning profile is invalid if it contains a disabled device.

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 and iOS Developer for iOS apps, and Automatic and Mac Developer for Mac apps.

If you’re using a custom development provisioning profile, read Using Custom Provisioning Profiles 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 Using Custom Provisioning Profiles, 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, 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 pop-up menu, try refreshing the provisioning profiles, as described in Refreshing Provisioning Profiles in Xcode. If you are using an Xcode-managed provisioning profile, read Using Xcode-Managed Provisioning Profiles. If you are using a custom provisioning profile, read Using Custom Provisioning Profiles.

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 or Is Ineligible in the Scheme Toolbar Menu

If you have a project or workspace open and your connected iOS device isn’t listed as a Scheme toolbar menu, verify that:

  1. 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.

  2. 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.

Archiving and Submitting Issue

If you select an archive in the Archives window and the Validate and Submit button are disabled, verify that the archive contains a single top-level app.