Maaz Zindani

Loading the index…

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

Flutter deep link works while the app is open but not from a closed app

ErrorThe link opens the correct screen when the app is already running

Short 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.

  • Applies to Flutter 3.35, Dart 3.9, Android 14
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'
  2. 2Match what you see, then jump to its fix

    1. 1The print shows the route '/' or the home page loads before any link is handled.Routing code ignores the initial routeFix
    2. 2You 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. 3flutter --version prints a release older than 3.27 and no deep link reaches the app.An old Flutter version needs an explicit opt-inFix

What does the error look like?

  • The link opens the correct screen when the app is already running
  • From a fully closed app the link opens only the home screen
  • A 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.myapp

Confirmed by docs.flutter.dev

Did this fix it?

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.xml

2Fix

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 run

Confirmed by docs.flutter.dev

Did this fix it?

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.xml

2Fix

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 -v

Confirmed by docs.flutter.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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