Installation errors
Device Not in Provisioning Profile
Prove where a tester device falls out of the Ad Hoc authorization chain, refresh the correct profile, and verify the replacement IPA before delivery.
A device must appear in the provisioning profile embedded in the delivered Ad Hoc IPA. Registering its UDID in the Apple Developer portal is necessary, but it does not update an existing profile or an IPA that was already produced.
The repair is to prove every link in the authorization chain, refresh the first stale state, and verify the replacement artifact before sending it again.
The complete authorization chain
physical iPhone
→ correct UDID
→ correct Apple Developer team
→ registered and active device record
→ Ad Hoc profile selects that device
→ IPA embeds the refreshed profile
→ app signature is consistent with that profile
→ supported installation pathIf any arrow is assumed rather than verified, “device not in profile” can survive several rebuilds.
The timing mistake that causes most confusion
An IPA contains a snapshot of its provisioning profile. When a tester is registered after the IPA was exported:
- the Apple team gains a device record;
- the old profile remains unchanged until edited or regenerated; and
- the old IPA still embeds its old profile forever.
Downloading a new profile beside the IPA, uploading the same IPA again, or changing the link does not modify the app bundle. Produce a new correctly signed artifact that embeds the refreshed profile.
Step 1: verify the physical iPhone’s UDID
Use the supported Finder or Xcode path and copy the identifier from the actual device. Compare it character for character with the submitted value. The find iPhone UDID guide covers retrieval, and the browser-local UDID Validator can normalize separators and catch obvious format errors without uploading the value.
A valid-looking hexadecimal string is not proof that it belongs to the client’s current phone. Confirm the device label and consent as part of the handoff.
Step 2: verify the Apple Developer team record
Open Devices in Certificates, Identifiers & Profiles under the team that owns the app. Confirm the UDID is registered, active, and associated with the intended platform and recognizable device name.
Apple requires a registered device to create Development or Ad Hoc profiles. A device in another client team, an inactive record, or a record created with the wrong identifier cannot authorize this build. Follow register an iPhone UDID if the record is absent.
Do not use shared Apple accounts, certificate pools, Enterprise credentials, or another organization’s team as a workaround.
Step 3: verify the profile selected the device
For a manually managed Ad Hoc profile, open the exact profile for the app and confirm the correct App ID, active distribution certificate, and client device are selected. Save or regenerate it, then download the result.
Apple notes that Xcode-managed distribution profiles may not appear in the account portal. Keep one signing model for the release: if Xcode automatic signing owns the profile, refresh through that workflow rather than creating a second ambiguous manual profile.
The add-device-to-profile guide covers manual and automated refresh choices in detail.
Step 4: inspect the profile embedded in the IPA
Work on a copy of the exact file behind the client link:
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 identifying fields and device list:
plutil -extract Name raw -o - /tmp/client-profile.plist
plutil -extract UUID 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.plistSearch the ProvisionedDevices output for the normalized target UDID. Apple uses this property for profiles that authorize a specific device list. If it is absent, the delivered IPA cannot gain it at install time.
Use Inspect a Provisioning Profile Inside an IPA for the full field interpretation and Apple’s warning that profile internals are diagnostic evidence, not a stable product API.
Step 5: prove the app and profile are consistent
A matching device is necessary but not sufficient. Check the app signature:
codesign --display --verbose=4 "$APP_PATH" 2>&1
codesign --display --entitlements :- "$APP_PATH"
codesign --verify --strict --verbose=4 "$APP_PATH"Compare the app’s team and application identifier, entitlements, and signing authority with the profile. If the device list is correct but the artifact was signed with a different identity or incompatible entitlements, use the IPA signature inspection guide and certificate/profile mismatch guide.
Inspect extensions and other nested signed bundles as well. The main app may be correct while a bundled extension carries a mismatched profile.
Step 6: eliminate stale artifacts and duplicate links
Record a checksum for the final IPA and compare it with the file served to the client:
shasum -a 256 ClientBuild.ipaRetire older release links or label them clearly. A frequent failure pattern is “profile regenerated, new IPA exported, old IPA still delivered” because a manifest, CDN object, message, or upload dashboard points at the earlier binary.
Do not overwrite files invisibly while preserving the same release record. Make it possible to identify which profile and build the client actually received.
What “works on one iPhone but not another” tells you
If the exact same IPA installs on one intended iPhone but not another, the successful install proves the artifact can pass at least one device context. It does not prove the failing phone is in the embedded profile.
Compare the two UDIDs first. If both appear in ProvisionedDevices, move next to OS/app compatibility, device state, and the exact installation path. If neither device can install, widen the diagnosis to bundle identity, profile expiry, certificate/profile consistency, damaged signing, and delivery. The Unable to Install App hub routes those branches.
Repair sequence
- Validate the failing physical device’s UDID.
- Register it in the correct Apple Developer team.
- Refresh the intended Ad Hoc profile with that device.
- Rebuild from source or perform an authorized re-sign with compatible app-owner assets.
- Inspect the replacement IPA’s embedded profile and signature.
- Install that exact IPA on a representative target device.
- Update the client link and retire stale artifacts.
For controlled automation, Fastlane device registration can handle a reviewed registration step, but profile refresh, rebuild, and artifact verification still remain. For the consent and client communication layer, use the client-device onboarding workflow.
IPAFlow is in Private Beta / In Development to explore this authorized chain as one traceable workflow. It does not bypass device limits or Apple ownership rules. Review the product boundaries if repeated device intake, profile refresh, artifact replacement, and client support are the problem your team needs to reduce.