Installation errors
Unable to Install App on iPhone
Diagnose an iPhone installation failure in evidence-first order across delivery, device authorization, embedded profile, signing, bundle identity, expiry, and artifact version.
“Unable to Install App” is a symptom, not a diagnosis. Do not start by recreating certificates or sending another link. First identify whether the failure is in delivery, device authorization, signing, the IPA itself, or a mismatch between the installation method and the build’s distribution type.
The fastest path is to hold the IPA constant, compare evidence, and stop at the first proven mismatch.
Capture the failure before changing anything
Record:
- the exact IPA filename, version, and build number;
- its bundle identifier and expected Apple Developer team;
- the physical iPhone model, iOS version, and validated UDID;
- the intended distribution method;
- the installation path and URL used;
- the exact alert text and the point where it appears; and
- whether this exact IPA installs on another intended device.
Avoid vague statements such as “the build works.” A different IPA, an older link, or a device authorized by another profile is not a valid comparison.
Step 1: does the same IPA install on another intended device?
If the same binary installs on one intended iPhone but not another, the artifact is not automatically good, but the difference is highly useful. Compare device authorization, OS compatibility, and the actual install path before replacing global signing assets.
For an Ad Hoc build, start with the failing UDID and the profile’s ProvisionedDevices list. Use Device Not in Provisioning Profile for that focused branch.
If the same IPA fails on every intended device, move signing, expiry, bundle identity, artifact integrity, and delivery earlier in the investigation.
Step 2: is the device supposed to be authorized?
Confirm the actual distribution type. A Development or Ad Hoc build is device-bound. The iPhone must be registered in the correct Apple Developer team and selected in the profile embedded in the app. TestFlight and App Store builds use different authorization paths; an installation technique for one type does not convert another.
Do not infer authorization from a client name in the portal. Validate the physical device’s UDID and compare it with the final artifact.
Step 3: inspect the embedded profile
Work on a copy of the IPA:
unzip -q ClientBuild.ipa -d ClientBuild-unpacked
APP_PATH=$(find ClientBuild-unpacked/Payload \
-maxdepth 1 -name '*.app' -print -quit)
security cms -D \
-i "$APP_PATH/embedded.mobileprovision" \
-o /tmp/client-profile.plistRead the fields that discriminate among common failures:
plutil -extract Name raw -o - /tmp/client-profile.plist
plutil -extract ExpirationDate raw -o - /tmp/client-profile.plist
plutil -extract Entitlements.application-identifier raw \
-o - /tmp/client-profile.plist
plutil -extract ProvisionedDevices xml1 \
-o - /tmp/client-profile.plistApple identifies ProvisionedDevices as the device list for profiles that apply to specific devices, ExpirationDate as the validity limit, and application-identifier as the App ID authorization. Use Inspect a Provisioning Profile Inside an IPA for field interpretation rather than building a permanent parser around an internal format Apple says can change.
Step 4: inspect signing identity and entitlements
codesign --display --verbose=4 "$APP_PATH" 2>&1
codesign --display --entitlements :- "$APP_PATH"
codesign --verify --strict --verbose=4 "$APP_PATH"A profile authorizes specific signing certificates and entitlement limits. The signing machine also needs the matching private key when producing a replacement. If the signature and profile do not belong to the same authorization set, follow the certificate/profile mismatch guide.
If iOS reports an integrity-specific message or verification fails, continue with App Integrity Could Not Be Verified and the IPA signature inspection guide.
Step 5: verify the bundle ID and App ID
plutil -extract CFBundleIdentifier raw \
-o - "$APP_PATH/Info.plist"Compare the bundle identifier with the bundle-ID portion of the profile’s application-identifier. Also inspect nested extensions: each signed target can have its own bundle ID, entitlements, and profile. A matching main app does not prove every extension is compatible.
Use Bundle ID and Provisioning Profile Mismatch when this comparison fails.
Step 6: verify profile and certificate expiry
The embedded profile—not a newer file on the developer Mac—controls the delivered IPA. If its ExpirationDate has passed, regenerate the correct profile and produce a replacement artifact. See Expired Provisioning Profile.
Certificate expiry and profile expiry are separate. If the signing identity is expired or unavailable, follow Expired iOS Distribution Certificate before rebuilding. Do not revoke unrelated certificates as a diagnostic experiment.
Step 7: verify the delivery layer
Only after the artifact and target device appear compatible should you blame the link.
For a hosted flow, verify that the tester is using the intended release URL, the link has not expired, access controls permit the download, and redirects do not replace the IPA or manifest response with HTML. If an itms-services handoff is involved, inspect the link, HTTPS manifest, referenced IPA URL, and response sequence separately with the dedicated link guide.
A new URL pointing to the same stale IPA is not a repair.
Step 8: rebuild or re-sign only after finding the mismatch
Choose the smallest corrective action supported by evidence:
- register the correct device and refresh the profile;
- replace an expired profile or signing identity;
- select the matching App ID and entitlements;
- rebuild from source with the intended configuration; or
- perform an authorized re-sign when source is unavailable and compatible app-owner assets exist.
Afterward, repeat the signature, profile, bundle ID, expiry, and device checks on the replacement IPA. Then install that exact file on a representative intended device before changing the client link.
Failure classes at a glance
- Delivery/link: the client never receives the intended IPA, the hosted resource is wrong, or the manifest/HTTPS sequence fails.
- Device authorization: the UDID is wrong, belongs to another team record, is absent from the profile, or was added after the IPA was produced.
- Signing: certificate/profile mismatch, expired assets, incompatible entitlements, or a damaged re-sign.
- Artifact: wrong environment, stale build, unexpected signing identity, or duplicate links pointing at different binaries.
- Device/method: the installation path does not match the signing type, or the device/OS does not meet the app’s actual requirements.
Run the browser-local iOS Distribution Checklist if you need a short routing aid. The useful outcome is not another list of possible causes—it is knowing which fact to verify next.