A deep link or app link opens the browser, a chooser, or nothing instead of your app
Tapping the link opens Chrome instead of the appShort 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.
Fix it fast
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.app2Match what you see, then jump to its fix
- 1
adb with your package fails, or links tapped in a browser never offer your appThe intent filter is missing the BROWSABLE or DEFAULT categoryFix - 2
Your 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
The 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
get-app-links shows legacy_failure, none, or an error code for a hostThe assetlinks.json file cannot be fetched or does not matchFix
- 1
What does the error look like?
Tapping the link opens Chrome instead of the appThe disambiguation dialog shows other apps, or nothing happensDomain 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.xml2Fix
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 installDebugConfirmed by developer.android.com
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.xml2Fix
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.appConfirmed by developer.android.com
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.app2Fix
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.app3Verify
Wait a few minutes, then read the state again. The host must show verified.
adb shell pm get-app-links com.example.appConfirmed by developer.android.com
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.json2Fix
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 installDebug3Verify
Read the verification state after a few minutes.
adb shell pm get-app-links com.example.appConfirmed by developer.android.com
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
adb cannot start because something already holds its port
adb start-server failed
The adb server must bind local TCP port 5037, and every adb client talks to it there.
2 causes, each with a fixMobile apps
The phone shows as unauthorized and Android Studio will not run the app
adb devices lists the phone but Android Studio cannot deploy to it
An unauthorized phone means it has not trusted this computer's RSA key.
3 causes, each with a fixMobile 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 fixMobile apps
adb cannot connect to its daemon or start the server
* daemon started successfully *
The adb server is a background process on your computer that listens on TCP port 5037.
2 causes, each with a fixMobile apps
adb prints 'server version doesn't match this client; killing...'
adb server version doesn't match this client; killing...
adb runs a background server, and every adb command is a client.
3 causes, each with a fixMobile 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