Universal Links broken by ?mode=developer associated domains
Appending ?mode=developer to an associated domain tells iOS to fetch the association file directly from your server instead of through Apple’s CDN. It only works on devices with Associated Domains Development enabled, so shipping it means Universal Links do not work for your users.
Why it matters
Developer mode exists so you can iterate on an apple-app-site-association file without waiting for Apple’s CDN to pick up changes. It is a development convenience with no purpose in a shipped build.
The failure is quiet: links open in Safari instead of the app. Nothing errors, nothing is rejected, and it looks like the association file is wrong when the entitlement is what is wrong.
It is easy to leave behind because it is added in the middle of debugging exactly this feature, at the point where attention is on the server side.
The consequence is worth being clear about, because it is not a rejection. The app is approved, shipped, and every link you send in an email or a push notification opens a web page instead of the screen it was supposed to open. Attribution, onboarding from a shared link and password resets all quietly stop working as designed.
It is also invisible on your own devices, which are the ones most likely to have the development setting turned on from when you were testing. The feature works perfectly for the person checking it and for nobody else.
How to fix it
- Remove ?mode=developer from every entry in the com.apple.developer.associated-domains entitlement.
- Confirm your apple-app-site-association file is served over HTTPS at the domain root, without a redirect, as application/json.
- Test on a device that has never had the development setting enabled, which is the only device that behaves like a customer’s.
The guidelines behind it
Read from Apple’s App Review Guidelines as last updated October 16, 2026.
What ReviewAhead checks
Associated domains. Associated domains must not ship in developer mode.
- Each associated domain entry for a ?mode=developer override.
- Reports how many domains are configured when they are clean, so the entitlement itself is visible in the report.
- Names the specific domains carrying the override rather than only saying one does.
Apple’s own documentation for this requirement: developer.apple.com. Where this page and Apple disagree, Apple is right and this page is a bug.