Installation errors
Fix an itms-services IPA Install Link That Is Not Working
Diagnose an itms-services failure across the tap target, encoded manifest URL, HTTPS responses, manifest contents, IPA hosting, and signing.
An itms-services link is only the first step in a multi-step delivery path. Start with the exact URL, then verify browser behavior, manifest retrieval, IPA retrieval, HTTP responses, artifact identity, signing/profile authorization, and the distribution method. Rebuilding the same link rarely helps if the manifest serves HTML or the IPA is signed for the wrong context.
Confirm the Apple support boundary first
Apple’s current Deployment guide documents website-based itms-services installation for proprietary in-house apps built with an in-house provisioning profile. Its website requirements include an XML manifest, HTTPS-hosted IPA and manifest, and a certificate trusted by the device. Apple’s current Xcode help documents Xcode or Apple Configurator for exported Development and Ad Hoc IPAs on registered devices.
Do not use the in-house website recipe as proof that a historical itms-services://?action=download-manifest... recipe is a universally supported modern Ad Hoc installation mechanism. Historical or vendor-specific hosted-link behavior is environment-dependent. If a platform claims to install an Ad Hoc build through a hosted link, verify its current documentation and test the exact signing type on a real target device.
Evidence-first diagnostic sequence
1. Identify the landing-page or link failure
The documented shape is the itms-services scheme with action=download-manifest and an absolute HTTPS manifest URL in the url query parameter.
Confirm that:
- the scheme is exactly
itms-services; action=download-manifestis present;- the nested manifest URL is absolute and HTTPS;
- query-string characters inside the nested URL are encoded correctly; and
- a JavaScript click handler or redirect does not replace the custom-scheme navigation.
Test from the actual supported device and browser path. Record what happens after the tap: no navigation, an error page, a manifest request, or an installation prompt. A desktop browser is useful for inspecting resources but cannot prove an iOS install handoff works. Do not “fix” a landing-page failure by rewriting a manifest that has not yet been requested.
2. Verify manifest retrieval and syntax
Open the decoded manifest URL in a clean authenticated session and inspect the response:
curl -iL 'https://example.com/manifest.plist'The final response must be the intended XML property list—not a login page, access-denied HTML, CDN challenge, expired signed URL, or redirect loop. Record each HTTP status, final URL, redirect, TLS result, and content type. Apple documents text/xml for the plist in its in-house hosting guidance.
Validate that the property list parses and that its software-package asset points to the exact IPA you intend to deliver. Confirm the manifest bundle identifier and version fields agree with the intended release. A stale manifest can silently reference yesterday’s artifact or environment.
3. Verify IPA retrieval separately
Copy the IPA URL from the manifest and test it without relying on browser cookies:
curl -I -L 'https://example.com/ClientBuild.ipa'It must remain reachable over HTTPS from the device’s network. Check certificate trust, redirect targets, authorization headers or cookies, expiry on signed URLs, response size, and whether the CDN returns the binary rather than an HTML error. For Apple’s documented in-house website route, the IPA is fetched after the manifest; Apple warns against using a direct IPA link as the install trigger.
4. Verify the artifact identity before changing signing
Compare the delivered IPA checksum with the release record, then inspect its embedded profile and signature. A successful 200 response only proves that bytes were delivered; it does not prove that the bytes are the intended build, have the right bundle identifier, or can be authorized on the target device.
5. Separate signing, provisioning, and distribution-method failures
If the requests succeed but iOS reports that the app cannot be installed or its integrity cannot be verified, the link layer has done its job. Inspect the IPA:
- signature verifies;
- bundle ID matches the intended profile;
- profile is current and not expired;
- certificate is authorized by the profile;
- entitlements align; and
- the target device is authorized when the distribution method requires it.
An Ad Hoc profile requires selected registered devices; a valid link cannot add a device after the IPA is exported. An in-house enterprise app has a different program and provisioning context. If the distribution method does not match the audience or program eligibility, editing XML is not a remedy.
Use Check an IPA’s Code Signature, inspect the embedded provisioning profile, Unable to Install App, and Integrity Could Not Be Verified for the specific evidence at this layer.
6. Capture the smallest useful evidence set
Record the timestamp, device/OS, network, exact landing URL, decoded manifest URL, final HTTP statuses, redirect chain, TLS or content-type evidence, IPA checksum, bundle identifier, profile expiry, and device-authorization status where applicable. Remove tokens and personal data before sharing logs. This distinguishes a link failure from manifest content, IPA delivery, signing, provisioning, and distribution-method failures.
Do not fix the incident by disabling HTTPS validation, exposing the IPA publicly, or switching to an Enterprise profile without program eligibility. Run the Distribution Checklist against the actual artifact and delivery method.