Flutter deep link works while the app is open but not from a closed app
The link opens the correct screen when the app is already runningShort answer
On a cold start Flutter does not push the link; it starts the app with an initial route that holds the link path. If your routing ignores that initial route, or a deep link plugin fights Flutter's own handler, the app opens on the home screen. Handle the initial route, and opt out of Flutter's handler when a plugin owns links.
Fix it fast
1Find out which cause you have
Close the app completely, then send the link with adb and watch the first route the app receives. Add a print in onGenerateRoute or in your route parser to see it.
adb shell am force-stop com.example.myapp adb shell 'am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://example.com/details" com.example.myapp'2Match what you see, then jump to its fix
- 1
The print shows the route '/' or the home page loads before any link is handled.Routing code ignores the initial routeFix - 2
You use a package such as app_links, and its stream or initial-link call returns nothing on a cold start.A deep link plugin conflicts with Flutter's own handlingFix - 3
flutter --version prints a release older than 3.27 and no deep link reaches the app.An old Flutter version needs an explicit opt-inFix
- 1
What does the error look like?
The link opens the correct screen when the app is already runningFrom a fully closed app the link opens only the home screenA deep link plugin never receives the first link
Cause 1 of 3
Routing code ignores the initial route
1Check
On Android a cold start delivers the link path as the initial route (for example /deeplink). On iOS the app first gets / and then a pushRoute. With the Router API the path is parsed and setNewRoutePath is called. Your code has to cope with both.
grep -rn "initialRoute\|onGenerateRoute\|RouteInformationParser\|setNewRoutePath" lib/2Fix
Make sure the route table or the RouteInformationParser knows the link path, and do not hard-code the home screen over the initial route.
MaterialApp.router(
routerConfig: _router, // a router whose routes include '/details'
);3Verify
Repeat the force-stop and adb start from the first step; the details screen should be the first one shown.
adb shell am force-stop com.example.myappConfirmed by docs.flutter.dev
Cause 2 of 3
A deep link plugin conflicts with Flutter's own handling
1Check
Flutter handles deep links by default. The Flutter docs say that its default handler breaks a third-party deep link plugin.
grep -n "flutter_deeplinking_enabled" android/app/src/main/AndroidManifest.xml2Fix
If the plugin should own the links, turn Flutter's handler off inside the activity element. If Flutter should own them, remove the plugin and use the router.
<activity android:name=".MainActivity" ...>
<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />
</activity>3Verify
Rebuild, then repeat the cold-start test and check the plugin now sees the first link.
flutter runConfirmed by docs.flutter.dev
Cause 3 of 3
An old Flutter version needs an explicit opt-in
1Check
The Flutter app links guide says versions before 3.27 need the deep linking flag set to true in the manifest.
flutter --version
grep -n "flutter_deeplinking_enabled" android/app/src/main/AndroidManifest.xml2Fix
Upgrade Flutter, or add the flag to the activity.
<meta-data android:name="flutter_deeplinking_enabled" android:value="true" />3Verify
Run the adb cold-start command again.
flutter doctor -vConfirmed by docs.flutter.dev
How do I stop it coming back?
- Test every new link twice: once with the app running, once after force-stop.
- Keep one owner for deep links, either Flutter's router or one plugin, never both.
- Put the route for each link path in the router table when you add the intent filter.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Mobile apps
A deep link or app link opens the browser, a chooser, or nothing instead of your app
The disambiguation dialog shows other apps, or nothing happens
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.
4 causes, each with a fixMobile apps
Flutter request fails with SocketException: Failed host lookup
ClientException with SocketException: Failed host lookup
Failed host lookup means the app could not turn the host name into an IP address, so no request was sent.
4 causes, each with a fixMobile apps
Flutter Image.network shows nothing or throws when the image fails
EXCEPTION: resolving an image codec
Image.network throws an exception that goes to FlutterError.onError when a download or decode fails, so a 404 leaves a red screen or an empty box.
3 causes, each with a fixMobile apps
Flutter cannot open a file: OS Error No such file or directory
FileSystemException: Cannot open file, path = '...' (OS Error: No such file or directory, errno = 2)
Errno 2 means the exact path you gave does not exist on the device.
3 causes, each with a fixMobile apps
Flutter file write fails with Permission denied (errno = 13)
OS Error: Permission denied, errno = 13
Errno 13 means the operating system refused the file operation.
2 causes, each with a fixMobile apps
Flutter says Unable to load asset for an image or file that exists
The asset does not exist or has empty data.
Flutter only bundles files that pubspec.yaml lists.
4 causes, each with a fix