Why that IPA will not install

Installing a build on a test device can fail in about six different ways, and iOS reports most of them with the same unhelpful message. Here is how to tell them apart quickly.

First, identify the type of build

Signed for	Installs on	Notes
Development	Devices whose UDID is in the profile	The usual case for a team build
Ad Hoc	Devices whose UDID is in the profile, up to 100	For a wider test group
Enterprise	Any device, after trusting the certificate	In-house distribution only
App Store	Nothing, directly	Signed for store distribution and nothing else

The last row often causes confusion. An App Store build cannot be sideloaded. If someone gives you the build that was submitted for review and asks why it will not install, this is the reason.

Failure 1: the device is not in the profile

Symptom: fails immediately with a generic signature error.

A development or Ad Hoc profile contains a list of permitted device UDIDs. If the device is not on the list, the installation stops before it starts.

Fix: read the device’s UDID, add it to the profile in the developer portal, regenerate the profile, and rebuild. The rebuild is essential: the profile is embedded in the IPA, so editing it in the portal does not change an existing build.

Failure 2: the profile has expired

Symptom: the same as failure 1, but every device in the fleet stops working on the same day.

Development profiles typically expire after a year, and certificates expire too. When a whole test fleet stops accepting builds at once, this is almost always the cause.

Fix: renew, rebuild and redistribute. Expiry affects every device at once, including devices that worked yesterday. A UDID problem does not.

Failure 3: not enough storage

Symptom: the installation starts, progresses partway, then fails.

An installation needs space for both the package and the unpacked app at the same time, so a 200 MB IPA needs considerably more than 200 MB of free space. On a device with 1 GB free and a large app, this fails intermittently. That is worse than a consistent failure, because it looks like a signing problem that comes and goes.

Fix: check free space before investigating anything else. It takes five seconds and can save an hour.

Failure 4: the version number is lower

Symptom: “a newer version of this app is already installed”.

iOS does not downgrade an app in place. If the device has build 412 and you install build 409, nothing happens until the installed app is removed.

Fix: uninstall first. Export any container data you need before you do, because uninstalling deletes it.

Failure 5: the developer is not trusted

Symptom: the app installs, then does not launch, and a message about an untrusted developer appears.

This is not an installation failure. The app is on the device, but iOS does not run code signed by a certificate the user has not trusted.

Fix: on the device, go to Settings → General → VPN & Device Management, select the developer and trust it. You need to do this once per certificate per device.

Failure 6: entitlements the profile does not grant

Symptom: fails immediately. The error may mention entitlements.

The app requests a capability, such as push notifications, App Groups, HealthKit or associated domains, that the provisioning profile does not include. The signature is valid, but the permissions do not match.

Fix: enable the capability on the App ID, regenerate the profile and rebuild.

A diagnostic order that saves time

1. Free storage. Five seconds, and a surprisingly common cause.
2. Is the device’s UDID in the profile? Read the UDID from the device rather than from a spreadsheet.
3. Has the profile expired? Check the date, and check whether other devices stopped working at the same time.
4. Is a newer build already installed? Compare versions before uninstalling anything.
5. Did it install but not launch? Then the issue is trust, not signing.
6. Only then check the entitlements.

Fleet maintenance

Most of these problems stop if you keep three things up to date: a UDID list that matches the physical devices, a record of each profile’s expiry date, and a habit of reviewing installed profiles when a device joins or leaves the fleet. Each takes about five minutes and can save an afternoon later.