Debugger: DevTools/Metro is disconnecting from the websocket if the app is backgrounded - was: `AppState.addEventListener('change')` on Android seems to suddenly stop working

[NorseGaud]

Description

AppState.addEventListener('change' on Android seems to suddenly stop working.

Steps to reproduce

https://github.com/NorseGaud/expo-testing

npx expo run:android

Once up and running, background the app by switching to something like the Contacts app. Then, open a contact, create a contact, etc, and then come back. You won't see the active log. However, if you just background the app and don't do anything significant it will show active logs switching back.

React Native Version

0.79.3

Affected Platforms

Runtime - Android

Output of npx @react-native-community/cli info

❯ npx @react-native-community/cli info
info Fetching system and libraries information...
System:
  OS: macOS 15.5
  CPU: (8) arm64 Apple M2
  Memory: 121.03 MB / 24.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 21.7.3
    path: ~/.nvm/versions/node/v21.7.3/bin/node
  Yarn:
    version: 1.22.21
    path: /opt/homebrew/bin/yarn
  npm:
    version: 10.8.3
    path: ~/.nvm/versions/node/v21.7.3/bin/npm
  Watchman:
    version: 2025.04.14.00
    path: /opt/homebrew/bin/watchman
Managers:
  CocoaPods:
    version: 1.15.2
    path: /opt/homebrew/opt/ruby/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 24.5
      - iOS 18.5
      - macOS 15.5
      - tvOS 18.5
      - visionOS 2.5
      - watchOS 11.5
  Android SDK:
    API Levels:
      - "26"
      - "27"
      - "28"
      - "29"
      - "30"
      - "31"
      - "32"
      - "33"
      - "34"
      - "35"
      - "36"
    Build Tools:
      - 26.0.3
      - 30.0.3
      - 33.0.1
      - 34.0.0
      - 35.0.0
      - 36.0.0
    System Images:
      - android-26 | Google APIs Intel x86_64 Atom
      - android-28 | Google ARM64-V8a Play ARM 64 v8a
      - android-29 | Google Play ARM 64 v8a
      - android-30 | Google Play ARM 64 v8a
      - android-34 | Google APIs ARM 64 v8a
      - android-34 | Google Play ARM 64 v8a
      - android-35 | Google Play ARM 64 v8a
      - android-36 | Google Play ARM 64 v8a
      - android-UpsideDownCakePrivacySandbox | Google Play ARM 64 v8a
    Android NDK: Not Found
IDEs:
  Android Studio: 2025.1 AI-251.25410.109.2511.13665796
  Xcode:
    version: 16.4/16F6
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.13
    path: /usr/bin/javac
  Ruby:
    version: 3.3.6
    path: /opt/homebrew/opt/ruby/bin/ruby
npmPackages:
  "@react-native-community/cli":
    installed: 18.0.0
    wanted: ^18.0.0
  react:
    installed: 19.0.0
    wanted: 19.0.0
  react-native:
    installed: 0.79.3
    wanted: 0.79.3
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

info React Native v0.80.1 is now available (your project is running on v0.79.3).
info Changelog: https://github.com/facebook/react-native/releases/tag/v0.80.1
info Diff: https://react-native-community.github.io/upgrade-helper/?from=0.79.3&to=0.80.1
info For more info, check out "https://reactnative.dev/docs/upgrading?os=macos".

Stacktrace or Logs

LOG  AppState has come to the background! 0.6961324593405451
 LOG  AppState has come to the active! 0.6961324593405451

MANDATORY Reproducer

https://github.com/NorseGaud/expo-testing

Screenshots and Videos

appstate-bug.mov

[NorseGaud]

I tried on a raw react-native project and I am having issues reproducing. It looks like metro is disconnecting from the websocket if I background the app too long.

AppState has come to the background! 0.738891
console.js:654 Cannot connect to Metro.

Try the following to fix the issue:
- Ensure that Metro is running and available on the same network
- Ensure that your device/emulator is connected to your machine and has USB debugging enabled - run 'adb devices' to see a list of connected devices
- If you're on a physical device connected to the same machine, run 'adb reverse tcp:8081 tcp:8081' to forward requests from your device
- If your device is on the same Wi-Fi network, set 'Debug server host & port for device' in 'Dev settings' to your machine's IP address and the port of the local dev server - e.g. 10.0.1.1:8081

URL: 10.0.2.2:8081

Error: undefined

Maybe this is actually the issue... If the app is backgrounded too long, things die and that's expected? Really though? I need to be able to foreground/active my app and call the most up to date data from the DB for example. I can't have the listener dying on me.

[NorseGaud]

Ok, so the LogCat logs are super verbose compared to what metro has;

full_log.txt

I see the same thing I see in a raw react-native/metro app. Error occurred, shutting down websocket connection: Websocket exception

[NorseGaud]

Ok so I built a production version of the app and installed it in my emulator. It seems to be without issue.

So ultimately this looks to be a metro and/or development profile/build issue.

[cortinico]

Once up and running, background the app by switching to something like the Contacts app. Then, open a contact, create a contact, etc, and then come back. You won't see the active log. However, if you just background the app and don't do anything significant it will show active logs switching back.

Is the issue you're reporting related to the AppState.addEventListener API or related to the Debugger as it's a bit unclear from your comments. It seems like it's related to the debugger, can you confirm?

[NorseGaud]

Once up and running, background the app by switching to something like the Contacts app. Then, open a contact, create a contact, etc, and then come back. You won't see the active log. However, if you just background the app and don't do anything significant it will show active logs switching back.

Is the issue you're reporting related to the AppState.addEventListener API or related to the Debugger as it's a bit unclear from your comments. It seems like it's related to the debugger, can you confirm?

Sorry for the mess. It works just fine when I run a production app outside of metro and only happens when metro is running a development build.

[cortinico]

Sorry for the mess. It works just fine when I run a production app outside of metro and only happens when metro is running a development build.

Ok so perhaps @huntie or @robhogan can provide further insights on what's happening with the debugger connection here

[huntie]

@NorseGaud Hey — yeah unfortunately backgrounding the app on some platforms will close any open WebSocket connections, which will disconnect DevTools, since the JS engine and debugger server run on the target device. This is a bit of a limitation, pretty much only for the use case you are testing 😅