iOS code signing errors that block test build installs
· 7 min read
When an iOS test build will not install, the phone rarely tells you why. Most failures show one of two messages: "Unable to Install" with a note to try again later, or "This app cannot be installed because its integrity could not be verified." Neither message names the cause, and trying again later never helps. Almost every time, the cause is in the signing: the profile, the certificate or the entitlements embedded in the .ipa.
This guide goes through the signing problems that stop over the air installs of test builds, one at a time. For each one: what causes it, how to confirm it in a minute, and how to fix it. Confirming is the important part, because rebuilding blindly costs far more time than looking inside the file.
Start here: read the signing from the file
Before guessing, open the .ipa in the IPA inspector. It runs in the browser, so the build is not uploaded, and it shows the facts you need for every case below:
- distribution type: Ad Hoc, Development, Enterprise, App Store, or none,
- profile name, team name and ID, creation date and expiry with days left,
- signing certificate name,
- number of provisioned devices and the full UDID list,
- entitlements and minimum iOS version.
If you prefer the terminal, the same information is in the embedded profile:
unzip -o MyApp.ipa -d /tmp/myapp
security cms -D -i /tmp/myapp/Payload/MyApp.app/embedded.mobileprovisionThe output is a property list with ExpirationDate, ProvisionedDevices, Entitlements and DeveloperCertificates. Now match what you see to one of the cases below.
1. Wrong distribution type: an App Store or TestFlight build shared as a link
Cause. Builds exported for App Store Connect are meant for Apple to process and deliver through the App Store or TestFlight. They cannot be installed from a web link on any device.
Confirm. The inspector shows the distribution type as App Store. The profile has no device list.
Fix. Export the same archive again with the Release Testing method (the current Xcode name for Ad Hoc), or Debugging for a development build. In an export options plist, set method to release-testing. With Fastlane, use gym(export_method: "ad-hoc"). If the build is going to TestFlight anyway, install it through TestFlight instead of a link.
2. Device not in the profile
Cause. Ad Hoc and Development builds install only on devices whose UDID is in the embedded profile. This is the most common cause of "Unable to Install" for a new tester, or for a tester with a new phone.
Confirm. Ask the tester for their UDID (the free UDID finder reads it in Safari), then search the inspector's UDID list for it.
Fix. Register the device in Certificates, Identifiers and Profiles, edit and save the profile so it includes the device, download it, and export again. Registering the device alone is not enough: the old .ipa still carries the old list. The whole routine, including the yearly device limit, is in register devices for Ad Hoc builds.
3. Profile expired
Cause. Ad Hoc profiles are valid for about a year, and a profile cannot outlive the certificate it references. Once it expires, the build no longer installs, and apps already installed from it stop opening.
Confirm. The inspector shows the expiry date and days left. A negative number, or a date in the past, settles it. Builds uploaded to an AppForShare account also get a store readiness check that flags profile expiry.
Fix. Regenerate the profile (edit and save it in the portal, or let automatic signing refresh it), export again and send the new link. Testers need to install the new build; there is no way to extend a profile inside a build that is already on the phone.
4. Certificate revoked or expired
Cause. Apple's documentation says a provisioning profile that contains a revoked certificate becomes invalid. This often happens when someone on the team creates a new distribution certificate and revokes the old one to make room, without realising existing test builds depend on it.
Confirm. Compare the certificate name in the inspector with the certificates listed in your developer account. If the one in the build is missing or marked revoked, that is the cause. On your Mac, Keychain Access shows the certificate as revoked or not trusted.
Fix. Use a valid distribution certificate (create one if needed), regenerate every Ad Hoc profile that pointed at the old one, and export again. Then agree on a rule about who may revoke certificates. What breaks and what does not when a certificate is lost or revoked is covered in lost or revoked iOS distribution certificate.
5. Entitlements mismatch
Cause. The app's code signature claims a capability that the profile does not grant. Typical examples: push notifications, associated domains, App Groups, iCloud, or a keychain group added in Xcode after the profile was generated, or an extension whose own profile lacks the capability. iOS refuses to install a build whose entitlements are not covered by its profile, and this often shows up as the "integrity could not be verified" message.
Confirm. Compare the entitlements in the inspector with the capabilities enabled for the App ID. Watch out for extensions: every app extension has its own bundle ID and its own profile, and one stale extension profile is enough to block the install. The inspector lists the app extensions in the build. On a Mac you can also print what the binary claims:
codesign -d --entitlements :- /tmp/myapp/Payload/MyApp.appFix. Enable the capability on the App ID (and on the extension's App ID), regenerate the profiles so they include it, and export again. If you sign manually in CI, make sure every target is mapped to its updated profile in the export options.
6. Developer Mode off on iOS 16 and later
Cause. Since iOS 16, Development and Ad Hoc builds need Developer Mode turned on before they run. App Store and TestFlight installs do not, and Enterprise builds are not affected.
Confirm. The app installs, but tapping it shows an alert about Developer Mode, or the switch is off under Settings, Privacy and Security, Developer Mode.
Fix. Turn on Developer Mode, restart the phone, then confirm with Turn On and the passcode after the restart. Steps for testers are in how to enable Developer Mode on iPhone.
7. Enterprise build not trusted yet
Cause. Enterprise (in house) builds install on any device, but iOS asks the user to trust the developer before the first launch.
Confirm. The app installs but opening it shows an "Untrusted Enterprise Developer" message.
Fix. Settings, General, VPN and Device Management, select the developer profile and trust it. If that option is missing on a managed device, the organisation's device policy may block it.
Quick reference
| What the tester sees | Check in the inspector | Most likely cause |
|---|---|---|
| "Unable to Install", other testers are fine | UDID list | Device not in the profile |
| "Unable to Install" for everyone | Distribution type, expiry | App Store build, or expired profile |
| "Integrity could not be verified" | Entitlements, extensions, certificate | Entitlements mismatch or invalid certificate |
| Installs, then a Developer Mode alert | Distribution type | Developer Mode off |
| Installed app suddenly stops opening | Expiry, certificate | Profile expired or certificate revoked |
| "Untrusted Enterprise Developer" | Distribution type is Enterprise | Trust not granted yet |
If the problem is not signing at all (wrong iOS version, a device the build does not support, Safari issues), work through can't install an app on an iOS device.
Catch it before testers do
All of these checks take a minute in the IPA inspector, and it is free with no account. When the build looks right, upload it to AppForShare to get an install link and QR code for testers. Note that AppForShare does not re-sign builds: the fixes above happen in your Apple account and export, and the link installs exactly the file you uploaded. Builds in an account also get the store readiness check, including profile expiry, and a "what changed" view that compares provisioned devices with the previous build. You can create a free account to try it.
