Skip to main content
Tutorials

16 common iOS code signing and .ipa install errors, and how to fix them

Signing problems show up at three points. At build time KXBuild checks the certificate and provisioning profile, with the same error text as Xcode. At install time the phone refuses the app. At launch iOS blocks the app from running. This article collects the 16 most common errors across these three stages, each with the symptom, cause and fix, and ends with a checklist. For where to put certificates and profiles and how a build picks them, read Certificates and signing first.

The three things signing uses

Almost every signing error comes down to a mismatch between these three.

  • Certificate (.p12) contains the certificate and its private key. Apple Development is for on-device debugging. Apple Distribution is for the App Store, TestFlight, Ad Hoc and enterprise distribution. A .cer alone has no private key and can’t sign.
  • App ID is the Bundle ID plus its enabled capabilities (push notifications, iCloud, Sign in with Apple and so on). You manage it on the Identifiers page of your Apple Developer account.
  • Provisioning profile (.mobileprovision) ties together the team, the App ID, the certificates allowed to sign, the devices allowed to install (Development and Ad Hoc only) and the capabilities. It’s valid for one year.

KXBuild reads these files from the keychain folder. The keychain folder in the project root applies to that project only, and the one under KXBUILD_HOME is shared by all projects. See Put them in the keychain folder. When a file in the keychain folder can’t be read, the build log shows a warning starting with keychain:. Check those lines first.

Inspect a provisioning profile on Windows

A provisioning profile is a signed plist that OpenSSL can decode. Git for Windows ships with OpenSSL. In Git Bash, run openssl directly. In PowerShell, use the full path.

1& "C:\Program Files\Git\mingw64\bin\openssl.exe" smime -inform DER -verify -noverify -in .\keychain\MyApp_Dev.mobileprovision -out profile.plist

Open profile.plist in an editor. These are the keys that matter when troubleshooting.

Key Contents
Name The profile name. This is what PROVISIONING_PROFILE_SPECIFIER takes with manual signing
TeamIdentifier Team ID
Entitlements > application-identifier Team ID plus Bundle ID. A wildcard App ID ends in *
Other Entitlements keys Enabled capabilities, for example aps-environment for push notifications
ProvisionedDevices UDIDs of devices allowed to install. App Store profiles don’t have this key
ExpirationDate Expiration date

Build errors

No profiles for ‘com.example.myapp’ were found

Symptom The build stops at signing with a message like No profiles for 'com.example.myapp' were found: Xcode couldn't find any iOS App Development provisioning profiles matching 'com.example.myapp'. The log also lists the keychain folders it searched.

Cause The project uses automatic signing, and KXBuild found no provisioning profile in the keychain folder matching the Bundle ID and team. There are four common reasons. The profile isn’t in the keychain folder, or it’s in another project’s keychain folder. The profile has expired. The type is wrong: Debug with an Apple Development certificate needs a Development profile, and Release with an Apple Distribution certificate needs an App Store or Ad Hoc profile. Or the project has extension targets such as a widget or notification extension. Each extension’s Bundle ID (such as com.example.myapp.widget) needs its own profile, and the Bundle ID in the error is the extension’s.

Fix In your Apple Developer account, create a profile of the right type for the Bundle ID in the error, download it and put it in the keychain folder. Make sure the target’s Bundle ID matches the App ID in your account. You can check it under General > Identity in the Project Settings Editor. During development, if you don’t use special capabilities, a Development profile for a wildcard App ID (such as com.example.*) covers the main app and all extensions.

Provisioning profile “…” has app ID “…”, which does not match the bundle ID “…”

Symptom The project uses manual signing, and the build reports that the profile’s App ID doesn’t match the Bundle ID.

Cause The profile named in PROVISIONING_PROFILE_SPECIFIER was created for a different Bundle ID. This happens after changing the Bundle ID, copying signing settings from another project, or when a Bundle ID containing a variable such as $(PRODUCT_NAME) resolves to something unexpected.

Fix Go by the bundle ID in the error and create a matching profile in your account, or change the project’s Bundle ID back to the profile’s. If you’re unsure of the final value, use kxbuild project info to see each target’s resolved Bundle ID.

1kxbuild project info .\MyApp.xcodeproj

Provisioning profile “…” doesn’t include signing certificate “…”

Symptom The keychain folder has both a certificate and a profile, but the build says the profile doesn’t include this certificate.

Cause The profile was created with a different certificate selected. Most often the certificate expired or its private key was lost, a new certificate was created, and the profile is still the old one. Or everyone on the team has their own Development certificate and the profile only includes someone else’s.

Fix On the Profiles page in your account, edit the profile, select the current certificate, save and download it again, and replace the old file in the keychain folder. A Development profile can include every team member’s certificate, so one file works for everyone.

No signing certificate matching ‘…’ found

Symptom You see No signing certificate matching 'Apple Distribution' found, or with a team, No certificate for team '…' matching '…' found.

Cause The project’s CODE_SIGN_IDENTITY asks for a certain type of certificate and DEVELOPMENT_TEAM asks for a certain team, and the keychain folder has no unexpired certificate with a private key that satisfies both. Expired certificates are skipped, so this is usually the error you get after a certificate expires.

Fix Add a .p12 of the right type and team. To use a different certificate for just one build, override it with -D without changing the project file. See Override build settings for one build.

1kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution" -D DEVELOPMENT_TEAM=ABCDE12345

keychain: xxx.p12: pkcs12: decryption password incorrect

Symptom This warning appears at the start of the build log, usually followed by No signing certificate matching.

Cause password.properties has no password for this certificate, the password is wrong, or the file name doesn’t match the actual .p12 (it’s case-sensitive and must include the .p12 extension).

Fix Write one certificate per line as filename.p12=password, with no quotes around the password. If you’ve forgotten the password, combine the original private key and .cer into a new .p12 with a new password.

1development.p12=123456
2distribution.p12=123456

A similar warning is has no private key; codesign will fail unless the .p12 is re-exported with its key. It means the .p12 contains only the certificate. Export it again with the private key, from the computer that generated the CSR or from the Mac keychain.

Provisioning profile “…” doesn’t include the Push Notifications capability

Symptom The build says the profile doesn’t include a capability, such as Push Notifications, iCloud, Sign in with Apple, Associated Domains or App Groups, sometimes followed by doesn't include the aps-environment entitlement.

Cause The project’s entitlements file (the .entitlements that CODE_SIGN_ENTITLEMENTS points to) requests the capability, but the App ID doesn’t have it enabled, or the profile wasn’t regenerated after enabling it. A profile’s capabilities are fixed when it’s created. Capabilities you enable on the App ID later don’t carry over to existing profiles.

Fix On the Identifiers page, open the App ID, check the capability and save. Then on the Profiles page, edit every profile for that App ID (one each for Development, Ad Hoc and App Store), save and download them again. Wildcard App IDs can’t enable most capabilities, including push notifications, so apps that use them need an explicit App ID. If you don’t actually need the capability, remove its key from the entitlements file instead.

Install errors

When you install with kxbuild build --install, Build & Run in VS Code or kxdevice install and the phone refuses, the reason from iOS is printed. Signing problems start with app not properly signed for this device: ApplicationVerificationFailed, followed by the specific reason in parentheses.

doesn’t include the currently selected device

Symptom Xcode reports Provisioning profile "…" doesn't include the currently selected device at build time. KXBuild doesn’t bind a device at build time, so the same problem shows up at install time as the next error, A valid provisioning profile for this executable was not found.

Cause The ProvisionedDevices list in the Development or Ad Hoc profile doesn’t contain this phone’s UDID. This happens most often with a new phone or a colleague’s phone.

Fix Get the UDID first. With the phone connected, run the command below. The first column is the UDID. For connection problems, see Set up your device.

1kxdevice device list

Register the UDID on the Devices page, then on the Profiles page edit the profile, select the new device, save and download it again. Replace the old file in the keychain folder and rebuild. Registering the device without downloading the profile again does nothing.

A valid provisioning profile for this executable was not found

Symptom Install fails with a message like ApplicationVerificationFailed (Failed to verify code signature of … : 0xe8008015 (A valid provisioning profile for this executable was not found.)).

Cause The phone decides the profile in the app doesn’t allow it to install. There are four common reasons. The profile doesn’t include this phone’s UDID. The app was signed with an App Store profile and installed directly, but App Store builds can only be installed through TestFlight or the App Store. The profile or certificate has expired, or the certificate has been revoked. Or the app was re-signed or modified by hand, so the profile and signature don’t match.

Fix For debugging, use the Debug configuration, an Apple Development certificate and a Development profile that includes the device. To install Release builds for testers, use an Ad Hoc profile, which also has to include the device UDIDs. See “Distribute outside the App Store” in Release and App Store submission. To check which profile is in use, run kxdevice provisioning list to see the profiles installed on the phone, or decode the one in the keychain folder as shown above and check ProvisionedDevices and ExpirationDate.

The executable was signed with invalid entitlements

Symptom Install fails with error code 0xe8008016 and the message The executable was signed with invalid entitlements.

Cause The entitlements signed into the app go beyond what the profile allows. KXBuild already checks the main app against its profile at build time, so this error usually comes from an extension target signed with a profile from another team or one missing a capability, an app re-signed after hand-editing its entitlements, or an app re-signed by a third-party tool.

Fix Rebuild the whole project with KXBuild instead of re-signing an old build, so the main app and every extension are signed by the same team with the profile for their own Bundle ID. If an extension needs push notifications or App Groups, enable them on its own App ID too and regenerate its profile.

DeviceOSVersionTooLow, iOS version below the deployment target

Symptom Install fails with DeviceOSVersionTooLow, which in Xcode is The iPhone's iOS … doesn't match MyApp.app's iOS … deployment target. When installing from a web page or another tool, the phone only says “Unable to Install”.

Cause The project’s iOS Deployment Target (IPHONEOS_DEPLOYMENT_TARGET) is higher than the phone’s iOS version. New project templates and some third-party libraries set a fairly recent deployment target.

Fix Update the phone’s iOS if you can. To support older versions, lower the deployment target, as long as your code and dependencies don’t use APIs from newer versions. Change it under General > Deployment in the Project Settings Editor, or from the command line.

1kxbuild project add-setting -k IPHONEOS_DEPLOYMENT_TARGET -v 15.0 -t MyApp -P .\MyApp.xcodeproj

For CocoaPods projects, also lower platform :ios in the Podfile and run pod install again. See CocoaPods.

MismatchedApplicationIdentifierEntitlement, upgrade install fails

Symptom The app is already on the phone, and installing a new build fails with MismatchedApplicationIdentifierEntitlement or Upgrade's application-identifier entitlement string … does not match installed application's.

Cause The old version on the phone was signed by another team, or has a different App ID prefix. This happens after switching developer accounts, for example from a company account to a personal one.

Fix Uninstall the old version, then install. Uninstalling deletes the app’s local data.

1kxdevice apps uninstall com.example.myapp

Unable to Install, ipa distribution fails

Symptom A tester installs the ipa through a web link, a third-party distribution platform or a third-party device manager. After the progress completes, the phone says “Unable to Install” or the icon stays grayed out.

Cause These channels only show a generic failure. The real reason is usually one of the errors above. The most common is a device missing from the Ad Hoc profile, followed by an app signed with a Development or App Store profile, an iOS version below the deployment target, and a revoked certificate.

Fix Connect the phone to your computer with a cable and run kxdevice install MyApp.ipa. It prints the specific reason from iOS, which you can look up in this article. For external testers, TestFlight is easier than Ad Hoc because you don’t need to collect UDIDs.

Launch problems

Developer Mode Required

Symptom The app installs, but opening it shows “Developer Mode Required”, or the debugger can’t connect to debugserver.

Cause Since iOS 16, running apps signed with a development certificate and debugging both require Developer Mode.

Fix On the phone, go to Settings > Privacy & Security > Developer Mode and turn it on. The phone restarts. Unlock it and confirm. This switch only appears after the phone has been connected to a computer. If you can’t find it in Settings, use kxdevice to reveal it or turn it on directly. See devmode.

1kxdevice devmode reveal
2kxdevice devmode enable

Untrusted Developer

Symptom Opening the app shows “Untrusted Enterprise Developer” or “Untrusted Developer”, and the only option is Cancel.

Cause Apps signed with an enterprise In-House certificate, and apps signed with a free Apple ID, have to be trusted manually before the first launch. Development and Ad Hoc builds signed by an Apple Developer Program account usually don’t show this prompt.

Fix On the phone, go to Settings > General > VPN & Device Management, tap the developer name under “Enterprise App” or “Developer App”, then tap “Trust”. The phone needs a network connection, because iOS verifies the certificate online.

Expired or revoked certificate

Symptom The build reports No signing certificate matching or No profiles for … were found. Or development, Ad Hoc or enterprise builds already on the phone suddenly won’t open, crash at launch or say they can’t be verified.

Cause Certificates are valid for one year (enterprise certificates differ). Profiles last at most one year and become invalid when a certificate they include expires or is revoked. If someone clicks Revoke in the account, or deletes an old certificate after hitting the limit, every build signed with it stops working. Versions already on the App Store aren’t affected when a distribution certificate expires.

Fix Check the certificate status on the Certificates page. If it’s expired or revoked, request a new certificate with a new CSR (you can reuse the old private key to generate it), combine a new .p12 and put it in the keychain folder. Then on the Profiles page, edit every related profile, select the new certificate and download them again. Finally rebuild and reinstall. If your team shares a distribution certificate, make sure nobody else is using it to build before revoking it.

Apple Developer account limits

Device limit reached, can’t register new devices

Symptom When adding a device on the Devices page, you’re told the limit is reached and the button is disabled.

Cause Each membership year allows up to 100 devices per device type (iPhone, iPad, Apple Watch, Apple TV, Mac and so on). Deleting a device doesn’t free a slot right away. Deleted devices still count for the rest of the year.

Fix When your membership renews, Apple gives you a chance to clean up. Disable devices you no longer use then, and the freed slots take effect in the new year. Until then, use TestFlight for external testing, since it doesn’t use device slots, and reuse registered devices for internal testing.

Checklist

For any signing or install problem, check in this order. Most cases are found in the first three steps.

  1. Look at the warnings starting with keychain: at the top of the build log, and make sure every .p12 was read with no password or private key problems.
  2. Check the certificate. Type (Development or Distribution), team and expiration must match the project’s signing settings, which are under General > Signing in the Project Settings Editor.
  3. Check the profile. Decode it with OpenSSL and check that application-identifier matches each target’s Bundle ID, the type matches the current configuration, all capabilities are there, it hasn’t expired, and DeveloperCertificates includes the current certificate.
  4. Check the device. The ProvisionedDevices list in Development and Ad Hoc profiles must include this phone’s UDID. Check it with kxdevice device list.
  5. Check the phone. Developer Mode is on, iOS is not below the deployment target, and enterprise builds are trusted in VPN & Device Management.
  6. Connect a cable and run kxdevice install to get the specific reason from iOS, then look it up in this article.

If you still can’t solve it, contact us with kxbuild version and the full build log, as described at the end of Troubleshooting.