[Android] FATAL: "Session ID must be unique" crash when app restarts after aggressive OS kill (Oppo/Xiaomi/ColorOS) - MusicService.onCreate() needs defensive session cleanup

[sahilchouksey]

Bug Description

The app crashes with java.lang.IllegalStateException: Session ID must be unique when:

1. User plays audio in the app
2. The OS (especially Oppo ColorOS, Xiaomi MIUI) aggressively kills the app process WITHOUT calling onDestroy()
3. User reopens the app
4. MusicService.onCreate() attempts to create a new MediaLibrarySession while the old "zombie" session still exists in the Android system

This crash is FATAL and unrecoverable from JavaScript - it occurs in native code during MusicService.onCreate() before any JS error handling can execute.

Impact

• 150+ crashes in our production app
• ~90% on Oppo/ColorOS devices (known for aggressive battery optimization)
• 15 affected users with repetitive crashes (~10 crashes per user on average)
• 100% occur in background (app killed while in background)
• Users cannot use the app until they clear app data or device restarts

Root Cause Analysis

The crash happens because:

1. Oppo/ColorOS/MIUI aggressive kill behavior: These OEMs kill background apps using SIGKILL-style termination that bypasses onDestroy() - the MediaSession is never released
2. Zombie MediaSession: The old MediaSession remains registered in Android's MediaSessionManager even after the app process dies
3. No defensive cleanup in MusicService.onCreate(): When the app restarts, MediaLibrarySession.Builder.build() throws because a session with the same ID already exists

Normal Android:     App killed → onDestroy() → MediaSession.release() → Clean restart ✓
Oppo/ColorOS:       App killed (SIGKILL) → onDestroy() SKIPPED → Zombie MediaSession → Restart → CRASH 💥

Stack Trace

FATAL EXCEPTION: main
Process: com.example.myapp, PID: 32617
java.lang.RuntimeException: Unable to create service com.doublesymmetry.trackplayer.service.MusicService: java.lang.IllegalStateException: Session ID must be unique. ID=
    at android.app.ActivityThread.handleCreateService(ActivityThread.java:4158)
    at android.app.ActivityThread.access$1600(ActivityThread.java:233)
    at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2014)
    at android.os.Handler.dispatchMessage(Handler.java:107)
    at android.os.Looper.loop(Looper.java:241)
    at android.app.ActivityThread.main(ActivityThread.java:7582)
    at java.lang.reflect.Method.invoke(Native Method)
    at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:492)
    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:941)
Caused by: java.lang.IllegalStateException: Session ID must be unique. ID=
    at androidx.media3.session.MediaSession.<init>(MediaSession.java:726)
    at androidx.media3.session.MediaLibraryService$MediaLibrarySession.<init>(MediaLibraryService.java:727)
    at androidx.media3.session.MediaLibraryService$MediaLibrarySession$Builder.build(MediaLibraryService.java:705)
    at com.doublesymmetry.trackplayer.service.MusicService.onCreate(MusicService.kt:120)
    at android.app.ActivityThread.handleCreateService(ActivityThread.java:4146)
    ... 8 more

Steps to Reproduce

# 1. Start logcat capture
adb logcat -c && adb logcat -s AndroidRuntime:E ReactNativeJS:I

# 2. Open app and play audio (do this manually on device)

# 3. While audio is PLAYING, simulate Oppo-style aggressive kill:
adb shell am crash <your.package.name>

# 4. Immediately reopen the app manually (tap app icon)

# 5. CRASH occurs: "Session ID must be unique"

Why adb shell am crash works: This command simulates SIGKILL behavior - the process is terminated immediately without calling any lifecycle methods, leaving the MediaSession as a zombie.

Environment

• react-native-track-player version: 5.0.0-alpha0 (feat/media3-newarch branch)
• React Native version: 0.76.9
• Affected Android versions: Android 10 (~70%), Android 15 (~30%)
• Affected manufacturers:
  • Oppo/ColorOS: ~90% of crashes
  • Xiaomi/MIUI: ~5%
  • Transsion: ~3%
  • Others: ~2%

Proposed Solution

Modify MusicService.kt to defensively handle zombie sessions in onCreate():

// MusicService.kt - in onCreate()

@ExperimentalCoroutinesApi
override fun onCreate() {
    // ... existing timber setup ...

    fakePlayer = ExoPlayer.Builder(this).build()

    // ... existing openAppIntent setup ...

    // PROPOSED FIX: Wrap session creation in try-catch with cleanup
    try {
        mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
            InnerMediaSessionCallback()
        )
            .setBitmapLoader(CacheBitmapLoader(CoilBitmapLoader(this)))
            .setSessionActivity(
                PendingIntent.getActivity(
                    this,
                    0,
                    openAppIntent,
                    getPendingIntentFlags()
                )
            )
            .build()
    } catch (e: IllegalStateException) {
        if (e.message?.contains("Session ID must be unique") == true) {
            Timber.w("Zombie MediaSession detected, attempting recovery...")

            // Option A: Use a unique session ID based on timestamp
            mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
                InnerMediaSessionCallback()
            )
                .setId("rntp_${System.currentTimeMillis()}")
                .setBitmapLoader(CacheBitmapLoader(CoilBitmapLoader(this)))
                .setSessionActivity(
                    PendingIntent.getActivity(
                        this,
                        0,
                        openAppIntent,
                        getPendingIntentFlags()
                    )
                )
                .build()

            Timber.i("Recovery successful with new session ID")
        } else {
            throw e // Re-throw if it's a different error
        }
    }

    super.onCreate()
}

Alternative approaches:

1. Always use unique session ID: .setId("rntp_${System.currentTimeMillis()}") by default
2. Try to release old session first: Query MediaSessionManager and release stale sessions before creating new one
3. Store session ID in SharedPreferences: Increment it on each app launch to ensure uniqueness

Why JS-Level Fixes Don't Work

We attempted to catch this error in JavaScript:

try {
  await TrackPlayer.setupPlayer(options);
} catch (error) {
  if (error.message.includes('Session ID must be unique')) {
    // Recovery logic
  }
}

This doesn't work because:

• The crash happens in MusicService.onCreate() which is called during native service creation
• The error is thrown BEFORE setupPlayer() ever returns to JavaScript
• The entire process crashes at the native level, not at the JS bridge level

Timeline of crash:
13:24:39.795 │ JS: TrackPlayer.setupPlayer() called
13:24:39.795 │ NATIVE: MusicService starting...
13:24:39.822 │ NATIVE: MusicService.onCreate() → MediaLibrarySession.Builder.build()
             │ 💥 CRASH: "Session ID must be unique"
             │
             │ ⚠️ Only 27ms between JS call and native crash!
             │ The error is thrown BEFORE any JS catch block can run

Related Issues

• Crash on feat/media3-newarch (java.lang.IllegalStateException: Session ID must be unique) #2485 - Same crash reported, but marked as closed without a fix
• "Session ID must be unique. ID=" when building a session androidx/media#1115 - Underlying MediaSession issue in androidx.media3

Additional Context

Device kill behavior research (from dontkillmyapp.com):

Manufacturer	OS	Kill Behavior	% of our crashes
Oppo	ColorOS	Aggressive SIGKILL, no lifecycle	~90%
Xiaomi	MIUI	Similar aggressive kill	~5%
Vivo	FuntouchOS	Similar to Oppo	-
OnePlus	OxygenOS	Now merged with ColorOS	-

These OEMs have a combined market share of ~40% in Asia, making this a critical issue for apps targeting that region.

Workaround for Users (Not Ideal)

Users can temporarily fix by:

1. Settings > Apps > [App Name] > Battery > Don't optimize
2. Lock app in recent apps (prevents aggressive kill)

But this is not a sustainable solution - the library should handle this gracefully.

[lovegaoshi]

to bandaid this issue u can create sessions with uuid, but it just creates more zombie processes. since you have the offending system to know the tech issue behind the scenes, can you confirm if android allows u to see previous sessions service from a new app instance and ur new instance can kill it? otherwise how does app properly do clean up in these oses?

[sahilchouksey]

@lovegaoshi

Session Lifecycle & Zombie Cleanup Analysis

I added comprehensive logging to MusicService.kt and ran 16 crash/restart cycles to understand exactly what happens with MediaSessions. Here are my findings:

---

TL;DR

1. Can a new app instance see previous zombie sessions? → No (SecurityException)
2. Can a new app instance kill previous zombie sessions? → No (no API access)
3. Does it matter? → No - Android automatically GC's all sessions when process dies
4. Is the unique session ID fix correct? → Yes - it's the only viable solution

---

My Understanding of the Issue

The core problem occurs on aggressive OEMs (Oppo, Vivo, Xiaomi, ColorOS, etc.) when:

1. App is force-killed (SIGKILL) without calling onDestroy()
2. MediaSession remains in Android's MediaSessionManager as a "zombie"
3. App restarts and tries to create a new MediaSession with the same hardcoded ID ("rntp_session")
4. Android rejects it: IllegalStateException: Session ID must be unique
5. App crashes on restart

The fix generates a unique session ID per launch (rntp_session_${timestamp}), so even if zombies exist, the new session doesn't collide with them.

But the question remains: Can we instead detect and kill zombie sessions from a new app instance? After extensive testing, the answer is No - and more importantly, we don't need to.

---

Complete Event Timeline (16 State Transitions)

#	Time	Event	PID	Sessions Before	Sessions After	Zombie Cleaned?
1	14:09:23	App Start	29496	-	Total=1	N/A
2	14:10:43	CRASH	29496→29977	1 active	Total=0 → Total=1	✅ YES
3	14:10:55	Race Restart	29977 (same)	1 active	Total=1 → Total=2	❌ Same PID
4	14:14:03	CRASH	29977→30620	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!
5	14:15:44	CRASH	30620→31043	1 active	Total=0 → Total=1	✅ YES
6	14:15:52	Race Restart	31043 (same)	1 active	Total=1 → Total=2	❌ Same PID
7	14:17:01	CRASH	31043→31363	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!
8	14:17:08	Race Restart	31363 (same)	1 active	Total=1 → Total=2	❌ Same PID
9	14:18:28	CRASH	31363→795	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!
10	14:18:34	Race Restart	795 (same)	1 active	Total=1 → Total=2	❌ Same PID
11	14:19:42	CRASH	795→2061	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!
12	14:19:49	Race Restart	2061 (same)	1 active	Total=1 → Total=2	❌ Same PID
13	14:21:08	CRASH	2061→2841	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!
14	14:22:21	CRASH	2841→3190	1 active	Total=0 → Total=1	✅ YES
15	14:22:28	Race Restart	3190 (same)	1 active	Total=1 → Total=2	❌ Same PID
16	14:24:04	CRASH	3190→3615	2 (1+zombie)	Total=0 → Total=1	✅ BOTH cleaned!

---

Key Finding #1: Sessions ARE Automatically Cleaned on Process Death

Every time the PID changes (process truly dies), the new process starts with Total=0:

PID 29977 (had 2 sessions) → CRASH → PID 30620 starts with Total=0 ✅
PID 31043 (had 2 sessions) → CRASH → PID 31363 starts with Total=0 ✅
PID 31363 (had 2 sessions) → CRASH → PID 795 starts with Total=0 ✅
... (pattern continues for all 8 PID transitions)

Conclusion: Android's MediaSessionManager automatically garbage collects all sessions when the owning process terminates.

---

Key Finding #2: Zombies Only Exist Within Same PID (Bounded)

The "zombie" scenario only happens due to Android's service restart race condition (executeNesting=2):

14:15:46 PID 31043: onCreate() → Session Created
14:15:46 PID 31043: onDestroy() CALLED (race condition!)
14:15:46 ActivityManager: "executeNesting=2" warning
14:15:52 PID 31043: onCreate() again (same PID reused!)
14:15:52 PID 31043: ⚠️ FOUND UNRELEASED SESSION FROM SAME PID
14:15:52 PID 31043: New session created → Total=2 (1 active + 1 zombie)

Important: Maximum zombies is 2 per PID lifetime (never saw Total=3 or higher in 16 cycles)

---

Key Finding #3: Cannot Query/Kill Sessions from New Process

// Attempted in MusicService.onCreate():
val mediaSessionManager = getSystemService(Context.MEDIA_SESSION_SERVICE) as MediaSessionManager
val sessions = mediaSessionManager.getActiveSessions(componentName)
// Result: SecurityException - need MEDIA_CONTENT_CONTROL permission

Log output:

RNTP-SESSION: Cannot query active sessions (SecurityException - need MEDIA_CONTENT_CONTROL)
RNTP-SESSION: This is expected behavior, using internal tracking instead

Why can't we access it?

API	Permission Required	Available to 3rd Party Apps?
MediaSessionManager.getActiveSessions()	MEDIA_CONTENT_CONTROL	❌ No (system only)
MediaSession.release()	Must own the session	❌ No (can't release others')
ActivityManager.killBackgroundProcesses()	KILL_BACKGROUND_PROCESSES	✅ Yes, but doesn't help with MediaSession

---

Why the Original Crash Happens (Root Cause)

The crash occurs in a very specific race condition window:

Timeline of the crash scenario:
================================

T+0ms:    App force-killed (SIGKILL) - onDestroy() NOT called
T+0ms:    MediaSession "rntp_session" becomes zombie (still registered in MediaSessionManager)
T+1000ms: Android schedules service restart
T+1000ms: New MusicService.onCreate() starts
T+1000ms: Tries to create MediaSession with ID "rntp_session"
T+1000ms: 💥 CRASH: "Session ID must be unique" (zombie still exists!)

WITH THE FIX:
T+1000ms: Tries to create MediaSession with ID "rntp_session_1768120763551"
T+1000ms: ✅ SUCCESS (unique ID, no collision with zombie)

The zombie eventually gets GC'd, but during that brief window (~few seconds), the hardcoded ID causes collisions.

---

Visual Summary

PROCESS LIFECYCLE & SESSION CLEANUP
====================================

PID 29977                    PID 30620                    PID 31043
┌──────────────┐            ┌──────────────┐            ┌──────────────┐
│ Session A    │            │ Session C    │            │ Session D    │
│ (zombie)     │            │ (active)     │            │ (zombie)     │
│ Session B    │   CRASH    │              │   CRASH    │ Session E    │
│ (active)     │ ────────►  │ Total: 1     │ ────────►  │ (active)     │
│ Total: 2     │            │              │            │ Total: 2     │
└──────────────┘            └──────────────┘            └──────────────┘
       │                           │                           │
       ▼                           ▼                           ▼
   PID DIES                    PID DIES                    PID DIES
   A & B GC'd ✅               C GC'd ✅                   D & E GC'd ✅
       │                           │                           │
       ▼                           ▼                           ▼
┌──────────────┐            ┌──────────────┐            ┌──────────────┐
│ NEW PID      │            │ NEW PID      │            │ NEW PID      │
│ Total: 0 ✅  │            │ Total: 0 ✅  │            │ Total: 0 ✅  │
└──────────────┘            └──────────────┘            └──────────────┘

---

Implementation

// In MusicService.kt - MediaSessionService initialization
val sessionId = "rntp_session_${System.currentTimeMillis()}"
// or: "rntp_session_${UUID.randomUUID()}"

Both work equally well. Timestamp is more debuggable in logs.

---

Reproduction Steps (What Worked For Me)

If you want to reproduce and test this issue yourself:

Prerequisites:

• Android device connected via ADB
• App with react-native-track-player installed (without the fix)

Step 1: Setup device to simulate aggressive OEM behavior

# Enable battery saver mode
adb shell settings put global low_power 1

# Mark device as unplugged (prevents charging state from affecting behavior)
adb shell dumpsys battery unplug

# Note: After ~60s of no activity, the device will automatically go idle 
# and lock the screen - this triggers the aggressive OEM kill behavior

Step 2: Start logcat monitoring

adb logcat -c && adb logcat -s RNTP-SESSION:D RNTP-LIFECYCLE:D ActivityManager:W AndroidRuntime:E

Step 3: Reproduce the crash

# Launch your app and start audio playback (creates the MediaSession)

# Force crash the app (simulates SIGKILL without onDestroy)
adb shell am crash <your.package.name>

# Wait 1-2 seconds, then reopen the app
# WITHOUT THE FIX: App crashes with "Session ID must be unique"
# WITH THE FIX: App starts normally

# Repeat multiple times to see the pattern

Step 4: Reset device state after testing

# Disable battery saver
adb shell settings put global low_power 0

# Reset battery state to normal
adb shell dumpsys battery reset

---

Test Environment

• Device: Motorola (Android 10, API 29)
• Package: com.example.myapp
• Library: react-native-track-player@5.0.0-alpha0
• Test method: adb shell am crash com.example.myapp (16 cycles)
• Battery saver: Enabled (simulates aggressive OEM behavior)
• Device state: Unplugged (auto-idles after ~60s of inactivity)

[lovegaoshi]

thabk you for the thorough investigation.

i only have samsung and pixels. i cant reproduce exactly this behavior but will take a look at rmulating via adb when i have time.

ehat i dont understand is ur claiming coloros sigkills the activity and the mediaservice lingers but eventually is GCed - how does playback behave in that regard? bc theres service stopping logic in onTaskRemoved the service can in fact live without activity and can couple or decouple as configured. from ur description i can only deduce the service is killed as well while onDestory doesnt trigger to release mediasession causing a resource leak.

i would still recommend before catching mediaSessions builder, find resources on how to manage gracefully shutting down in coloros. they have to have some kind of mechanism, otherwise they risk huge resource leak issues.

[jbernhardt23]

We were facing the same issue, and after following some suggestions from Cursor and the official docs for Audio services on Android, I created this patch that essentially releases the media session always on onDestroy and on onCreate prevents recreating the session if already initialized. We also ensured that setupPlayer from the JS Code is initialized only once through the app lifecycle.

diff --git a/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt b/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt
index b495b5a..752042e 100644
--- a/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt
+++ b/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt
@@ -97,28 +97,35 @@ class MusicService : HeadlessJsMediaService() {
                 return "RNTP-${element.className}:${element.methodName}"
             }
         })
-        fakePlayer = ExoPlayer.Builder(this).build()
-        val openAppIntent = packageManager.getLaunchIntentForPackage(packageName)?.apply {
-            flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
-            // Add the Uri data so apps can identify that it was a notification click
-            data = Uri.parse("trackplayer://notification.click")
-            action = Intent.ACTION_VIEW
-        }
-        mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
-            InnerMediaSessionCallback()
-        )
-            .setBitmapLoader(CacheBitmapLoader(CoilBitmapLoader(this)))
-            // https://github.com/androidx/media/issues/1218
-            .setSessionActivity(
-                PendingIntent.getActivity(
-                    this,
-                    0,
-                    openAppIntent,
-                    getPendingIntentFlags()
-                )
-            )
-            .build()
+
         super.onCreate()
+
+        if(!::mediaSession.isInitialized){
+            fakePlayer = ExoPlayer.Builder(this).build()
+
+            val openAppIntent = packageManager.getLaunchIntentForPackage(packageName)?.apply {
+                flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
+                // Add the Uri data so apps can identify that it was a notification click
+                data = Uri.parse("trackplayer://notification.click")
+                action = Intent.ACTION_VIEW
+            }
+
+            mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
+                InnerMediaSessionCallback()
+            )
+                .setId("${packageName}.media_session")
+                .setBitmapLoader(CacheBitmapLoader(CoilBitmapLoader(this)))
+                // https://github.com/androidx/media/issues/1218
+                .setSessionActivity(
+                    PendingIntent.getActivity(
+                        this,
+                        0,
+                        openAppIntent,
+                        getPendingIntentFlags()
+                    )
+                )
+                .build()
+        }
     }
 
     enum class AppKilledPlaybackBehavior(val string: String) {
@@ -792,10 +799,10 @@ class MusicService : HeadlessJsMediaService() {
 
     @MainThread
     override fun onDestroy() {
-        if (::player.isInitialized) {
-            Timber.d("Releasing media session and destroying player")
-            mediaSession.release()
-            player.destroy()
+        mediaSession.run {
+            player.release()
+            fakePlayer.release()
+            release()
         }
 
         progressUpdateJob?.cancel()

[lovegaoshi]

interesting. can you confirm onDestory is consistently called bc its previously reported odygenos does sigkill which should skip that? and if mediasession. created can be properly reused in mediaservice's oncreate? imo it should not work.

[prabhav-mehra]

is there any workaround for this? This issue has 3,070 crash events affecting 157 users. Unfortunately we had to migrate to alpha version to support new arch

[sahilchouksey]

@prabhav-mehra We are also using the alpha version, and this issue is occurring there as well. You can use the following fix:

--- a/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt
+++ b/node_modules/react-native-track-player/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt
@@ -104,9 +104,17 @@ class MusicService : HeadlessJsMediaService() {
             data = Uri.parse("trackplayer://notification.click")
             action = Intent.ACTION_VIEW
         }
+        // FIX: Use unique session ID to prevent "Session ID must be unique" crash
+        // This crash occurs when app is force-killed (no onDestroy called) and reopened.
+        // The previous MediaSession remains as a "zombie" in Android's static session map.
+        // Using a unique ID per app launch avoids the conflict.
+        // See: https://github.com/doublesymmetry/react-native-track-player/issues/2485
+        val uniqueSessionId = "rntp_session_${System.currentTimeMillis()}"
+        
         mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
             InnerMediaSessionCallback()
         )
+            .setId(uniqueSessionId)
             .setBitmapLoader(CacheBitmapLoader(CoilBitmapLoader(this)))
             // https://github.com/androidx/media/issues/1218
             .setSessionActivity(