iOS Troubleshooting

  • Updated on Oct 20, 2025
  • Published on Feb 12, 2025
Prev Next

Overview

This guide lists out some of the most common challenges we see customers run into when trying to integrate the Branch iOS SDK.

To integrate the Branch iOS SDK, follow the steps in our iOS SDK Basic Integration guide.

Scenarios

App does not open

If your app is not opening when you click a Branch Deep Link, confirm that:

  1. The Branch iOS SDK has been integrated into your app successfully.

  2. Universal Links are enabled on the device (can only be disabled on iOS 9 and iOS 10). The iOS SDK Testing guide has steps on testing a Branch Deep Link, which will re-enable Universal Links on the device.

  3. No issues related to the actual creation of the Branch Deep Link.

  4. Your website is properly configured for Universal Links.

Link does not pass data

If Branch Deep Link data is not getting funneled to your app, confirm that:

  1. You are not having issues related to the app not opening.

  2. Your console logs are free of errors. To check this, you need to enable logging.

Deep links are long

If you find that your Branch Deep Links are long, this is because the app cannot make a connection to the Branch servers.

However, these long Branch Deep Links will still open the app and pass data.

Deferred deep linking issues

If deferred deep linking is broken, confirm that you have enabled NativeLink™.

Not doing so will cause deferred deep linking to be broken on devices with iOS 15+ installed and Private Relay enabled.

You can also test your deferred deep linking scenario with these steps.

Please note that you must have our Engagement product to have access to Branch Deferred Deep Linking.

iOS 26 with Safari

If you are testing on an iOS 26 device with Safari, please note that the user agent OS token gets frozen at 18_6.

In this case, Branch labels iOS 26 devices as iOS 18.6 devices due to the data provided in the user agent. This prevents a match being made, and breaks deferred deep linking.

Branch automatically fixes cases where the os_version is provided by the DSP. For cases where os_version is not available, we strongly recommend using NativeLink™.

Deep link routing issues

If you're having issues with deep link routing, confirm that:

  1. You have followed the appropriate steps in our guide for navigating to content.

  2. You test the routing with the ?bnc_validate=true param.