How I troubleshoot iOS Universal Links

#universal-link#ios#troubleshooting

Universal Links can be frustrating when a working integration suddenly stops opening the app. My team ran into that exact problem.

The project configuration had worked before, but the links started opening in Safari. We needed a way to narrow down the cause.

This guide focuses on an existing integration. If you are setting up the feature, start with Apple’s Universal Links documentation.

Confirm the basic association#

Before troubleshooting, confirm that your project has a two-way association between the app and website. This association specifies the URLs that your app handles.

Host the apple-app-site-association file at /.well-known/apple-app-site-association on your website. Add the Associated Domains capability with an applinks configuration to your Xcode project.

Check where the link opens#

If the link opens your app’s home screen, the basic association is working. The remaining problem is probably in the app’s URL routing.

Handle the URL in the app, then route it to the correct screen or flow for that endpoint.

If the link opens Safari, inspect the Apple App Site Association (AASA) file. This check is useful when the same configuration worked before.

Test the link from Notes#

I use the Notes app for a quick check. Add each URL that you want to test. Then touch and hold a link to view its options.

If Universal Links are configured correctly, you should see two options:

Open in {Your App Name}
Open in Safari

Your choice sets the default behavior for future Universal Links from that domain. Repeat the test to select the other option.

If you do not see Open in {Your App Name}, check whether the AASA file is publicly accessible.

Inspect the public AASA file#

Run this command in Terminal:

curl -v https://{your-domain}/.well-known/apple-app-site-association

A 301 or 302 HTTP status code indicates a redirect. The hosted AASA file must be directly accessible.

A redirect is allowed when another app triggers the Universal Link. Safari opens first, then your app opens.
A 403 or 404 HTTP status code indicates an access problem. The file might not be public, or another rule might block it.

I encountered this issue when Cloudflare blocked all bot traffic to the website. Cloudflare classified AASA requests as bot traffic. Ensure that your configuration permits direct AASA access from all geographic locations and Internet Protocol (IP) addresses.

Check Apple’s cached AASA file#

Finally, verify which AASA file Apple’s content delivery network (CDN) has cached for your domain.

Open this URL in your browser: https://app-site-association.cdn-apple.com/a/v1/{your-domain}.

Alternatively, run this command in Terminal:

curl -v https://app-site-association.cdn-apple.com/a/v1/{your-domain}

Compare this response with the file on your website. The Apple CDN response is the version available to your app.

When you install the app, the device immediately downloads the AASA file from the CDN. The device checks for updates approximately once a week. Reinstall the app to download a newer file because the CDN has no direct invalidation option.

These checks helped my team separate an app routing problem from a website or CDN problem. I hope they make your next investigation a little easier.

If problems remain, see Apple’s TN3155: Debugging universal links.