📅 February 02, 2026
⏱ 10 min read
Mobile (iOS / Android)

How to Debug Universal Links That Don’t Open Your App

A comprehensive guide to troubleshooting why Universal Links might not be opening │ your iOS app, covering common issues with AASA files, app configuration, and │ device-specific debugging.

⭐ Intermediate

Debugging Universal Links that fail to open your app involves a systematic approach, checking both your app's configuration and your web server setup. Here's a comprehensive guide:

1. Verify Basic Setup & Test Environment

  • Real Device, Not Simulator: Universal Links often behave differently on simulators. Always test on a physical iOS device.
  • Delete and Reinstall App: After making changes, always delete the app from your device and reinstall it. This forces iOS to re-download the apple-app-site-association (AASA) file.
  • Test from Appropriate Sources: Universal Links won't work if you paste them directly into the browser's URL bar. Test by tapping links from other apps like Notes, Mail, iMessage, or Slack. Some apps like Instagram, Twitter, or Facebook might not support Universal Links directly.

2. Check apple-app-site-association (AASA) File

The AASA file is crucial for Universal Links. iOS downloads this file from your web server to determine which links your app can handle.

  • File Location: The AASA file must be hosted at https://yourdomain.com/apple-app-site-association or https://yourdomain.com/.well-known/apple-app-site-association.
  • HTTPS and No Redirects: The file must be served over HTTPS and without any 3xx redirects.
  • Content-Type Header: Ensure the server returns the correct Content-Type header for the AASA file.
  • JSON Validity: The AASA file must be a valid JSON and adhere to the specified schema. You can use online validators (like Branch.io's AASA validator) to check its correctness.
  • appID and Paths: Verify that the appID in your AASA file matches your app's Team ID and Bundle Identifier (e.g., ABC123DEF.com.example.app). Also, ensure the paths array correctly specifies the URL paths your app should handle.
  • Server Logs: Check your web server's HTTPS logs to confirm that the AASA file is being downloaded by iOS when your app is installed.

3. App Configuration in Xcode

  • Associated Domains Entitlement: In your Xcode project, go to the "Signing & Capabilities" tab and ensure "Associated Domains" is enabled. Add your domain in the format applinks:yourdomain.com.
  • Debug vs. Release: If debugging in development, ensure you're editing the Debug version of "Signing & Capabilities." To bypass the Apple Universal Links CDN in development, configure your debug domains like applinks:yourdomain.com?mode=developer.
  • App Delegate/Scene Delegate: Verify that your app's AppDelegate (or SceneDelegate for iOS 13+) correctly implements the application(_:continueUserActivity:restorationHandler:) method to handle incoming NSUserActivity objects for Universal Links.

4. Device-Specific Debugging

  • Console Logs: Connect your device to Xcode and open the Console (Window > Devices and Simulators > [Your Device] > Open Console). Filter the logs for "swcd" (Shared Web Credentials Daemon) to see if registering your Universal Link worked or failed.
  • Developer Settings (iOS 13+):
    • Enable "Developer Mode" in Settings > Privacy & Security > Developer Mode.
    • In Settings > Developer > Universal Links, enable "Associated Domains Development."
    • Use the "Diagnostics" tool in the Universal Links section to enter your Universal Link URL and check if it's valid for your installed app.
  • Restart Device: Restarting your device can clear iOS Universal Link caches and resolve issues.
  • Test on Different Devices/iOS Versions: This helps rule out device-specific configuration problems.
  • Re-enable Universal Links: If a Universal Link previously opened in Safari, it might have been disabled for that specific link. Long-press the link in an app like Notes and select "Open in [Your App Name]" to re-enable it. If you see a Smart App Banner in Safari, tapping "OPEN" in the banner can also re-enable Universal Links.

5. Advanced Troubleshooting

  • sysdiagnose Logs: For deeper insights, you can access sysdiagnose logs on your iOS device (Settings > Privacy & Security > Analytics & Improvements > Analytics Data). These logs can provide detailed information about how iOS is processing your Universal Links.
  • Third-Party Tools: Utilize tools like Apple's App Search API Validation Tool or other third-party validators to verify your website's configuration.

By systematically going through these steps, you can identify and resolve most issues preventing your Universal Links from opening your app.