Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A deep link or app link opens the browser, a chooser, or nothing instead of your app

ErrorTapping the link opens Chrome instead of the app

Short answer

A deep link only reaches your app if the intent filter is complete and, for http or https links on Android 12 and up, the domain is verified. Test the link with adb first. Then check four things: the BROWSABLE and DEFAULT categories, the data tags, domain verification, and the assetlinks.json file.

  • Applies to Android 12 (API 31) to Android 16, Android Gradle Plugin 8.x, adb from current platform-tools
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Fire the link at your package from the command line. If this opens your activity, the intent filter works and the problem is how the link is sent or verified.

    adb shell am start -W -a android.intent.action.VIEW \
      -d "https://www.example.com/gizmos/1" com.example.app
  2. 2Match what you see, then jump to its fix

    1. 1adb with your package fails, or links tapped in a browser never offer your appThe intent filter is missing the BROWSABLE or DEFAULT categoryFix
    2. 2Your app opens for links you did not plan for, or another host or scheme combination is wrongly acceptedSeveral data tags in one filter match more than you meantFix
    3. 3The link opens in the default browser, although the same filter worked before Android 12An http or https link is not a verified App Link (Android 12 and up)Fix
    4. 4get-app-links shows legacy_failure, none, or an error code for a hostThe assetlinks.json file cannot be fetched or does not matchFix

What does the error look like?

  • Tapping the link opens Chrome instead of the app
  • The disambiguation dialog shows other apps, or nothing happens
  • Domain verification state: legacy_failure

Cause 1 of 4

The intent filter is missing the BROWSABLE or DEFAULT category

1Check

Open the activity in the manifest. The filter needs the VIEW action plus both categories. Without BROWSABLE a browser link cannot resolve to the app. Without DEFAULT the activity starts only when the intent names the component.

grep -n -B3 -A12 "intent-filter" app/src/main/AndroidManifest.xml

2Fix

Complete the filter. The scheme is the minimum data attribute.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https"
          android:host="www.example.com"
          android:pathPrefix="/gizmos" />
</intent-filter>

3Verify

Reinstall and repeat the adb command from the first step.

./gradlew installDebug

Confirmed by developer.android.com

Did this fix it?

Cause 2 of 4

Several data tags in one filter match more than you meant

1Check

Data tags in one filter are merged, so two data tags with different schemes and hosts allow every combination of them.

grep -n "<data" app/src/main/AndroidManifest.xml

2Fix

Use one intent filter per unique scheme and host pair.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="example" android:host="gizmos" />
</intent-filter>

3Verify

Run the adb command for each URL you expect to work, and one you expect to be refused.

adb shell am start -W -a android.intent.action.VIEW -d "example://gizmos" com.example.app

Confirmed by developer.android.com

Did this fix it?

Cause 3 of 4

An http or https link is not a verified App Link (Android 12 and up)

1Check

Since Android 12 a generic web intent reaches your app only if your app is approved for that domain. Print the verification state for your package.

adb shell pm get-app-links com.example.app

2Fix

Add android:autoVerify="true" to the filter and publish a valid Digital Asset Links file for every host in it. Then re-run verification.

<intent-filter android:autoVerify="true">
    ...
</intent-filter>

adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app

3Verify

Wait a few minutes, then read the state again. The host must show verified.

adb shell pm get-app-links com.example.app

Confirmed by developer.android.com

Did this fix it?

Cause 4 of 4

The assetlinks.json file cannot be fetched or does not match

1Check

Android requests the file from the exact host in your filter. Fetch it yourself and compare it with your app.

curl -i https://www.example.com/.well-known/assetlinks.json

2Fix

Serve the file at https://HOST/.well-known/assetlinks.json for every host in your filters, then reinstall the app so verification runs again. On Android 15 and up the system re-verifies in the background and changes can take up to seven days to reach devices.

adb uninstall com.example.app
./gradlew installDebug

3Verify

Read the verification state after a few minutes.

adb shell pm get-app-links com.example.app

Confirmed by developer.android.com

Did this fix it?

How do I stop it coming back?

  • Test every link type with adb before you test it from a browser or a chat app.
  • Keep one intent filter per scheme and host so nothing is accepted by accident.
  • Check get-app-links in your release checklist, on a device that runs Android 12 or newer.
  • Do not rely on a custom scheme alone for links on your own domain. Verified App Links are the supported route.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.