[Due for payment 2026-06-04] [Sentry: APP-7B2] HybridApp iOS Fatal App Hang in Fabric ComponentDescriptorRegistry::findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN

[mountiny]

Sentry

https://expensify.sentry.io/issues/APP-7B2

Impact (snapshot at filing)

• Users (last 14d): ~36
• Platform: iOS, hybrid_app (HybridApp)
• Mechanism: AppHang, fatal — watchdog termination after 2000ms main-thread block

Stack trace (native, top frames)

main thread
  -> facebook::react::ComponentDescriptorRegistry::findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN

Suspected cause

The React Native Fabric infrastructure frame name explicitly flags an unsupported / known-broken lookup path. This is RN platform infrastructure (not application code), so the most likely outcome is a React Native version bump or a platform-team patch upstream.

Investigation suggestions

• Re-symbolicate a recent event in Sentry to recover the JS-side context that triggers the descriptor lookup.
• Check React Native release notes / issues for the findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN symbol — it's referenced in a few Fabric-era RN bugs.
• Compare iOS / device distribution with sibling Fabric crashes (APP-7CX, App#91229) to see if it correlates with the same device class.

Reproduction

Unknown deterministically — fires during the React commit phase under load.

Related

• Sibling Sentry IDs (if any): none identified — this is a distinct hang path from APP-7CX (+[YAPLJS callFunction:args:]) and APP-7FJ (generic main).
• Prior GH issues: none.

Issue Owner

Current Issue Owner: @mallenexpensify

[MelvinBot]

Proposal

What is the root cause of that problem?

The hang occurs in React Native Fabric's main-thread mount pipeline. During the commit phase, MountingCoordinator::pullTransaction acquires a scoped_lock and runs the shadow tree diff + mount synchronously on the main thread. Within this pipeline, AnimatedMountingOverrideDelegate::pullTransaction calls findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN for every animated mutation, which acquires a shared_lock on ComponentDescriptorRegistry::mutex_.

The 2000ms+ hang is caused by mutex contention: when a background thread lazily registers a new component descriptor via add() (which takes a unique_lock on the same mutex), all shared_lock readers on the main thread block. In HybridApp, Fabric interop's lazy registration of legacy OldDot view managers amplifies this contention. Meta's own header comment on this function says "This is broken. Please do not use."

Contributing factors specific to this app:

• Patches that disable view recycling for TextInput, Expo views, and Lottie increase Create/Delete mutation counts per transaction
• HybridApp's OldDot main-thread work competes with Fabric mounting
• The app uses RN 0.83.1 with Fabric fully enabled (RCT_NEW_ARCH_ENABLED=1)

What changes do you think we should make in order to solve the problem?

This is fundamentally an upstream React Native infrastructure issue — the function is internal to RN's Fabric renderer and is called by RN's own AnimatedMountingOverrideDelegate, UIManager, and RCTSurfacePresenter. The app cannot remove or bypass these call sites without patching RN.

Recommended approach — patch RN to eagerly register all component descriptors at startup, eliminating runtime add() calls that cause mutex contention:

1. Add a patch to ComponentDescriptorRegistry.cpp that pre-registers all known component descriptors during initialization rather than lazily during the mount phase
2. Alternatively, if the C++ native animated driver (cxxNativeAnimatedEnabled) is active, evaluate switching animated views to Reanimated (which bypasses AnimatedMountingOverrideDelegate entirely)

If patching is not viable, monitor for an upstream fix in RN 0.84+ — Meta is aware this function is broken (per the name and header comment) but has not yet replaced it. Filing an upstream RN issue linking this Sentry data would help prioritize the fix.

What alternative solutions did you explore? (Optional)

• Re-enabling view recycling: Would reduce mutation counts and mount phase duration, but the recycling was disabled to fix other bugs (TextInput state leaks, Expo view issues) — re-enabling risks regressions
• Moving mount work off the main thread: Not feasible without deep RN architecture changes; Fabric's mount phase is designed to run on the main thread for UIKit safety
• Downgrading from Fabric: Would eliminate this code path entirely but is a major regression and defeats the purpose of the new architecture migration

Investigation details

Related issues:

• Expensify/App#91229 — APP-7CX: HybridApp iOS Fatal App Hang in YAPLJS callFunction during onBarButtonItemSelected (sibling Fabric hang, different code path)
• Expensify/App#91293 — APP-7FJ: HybridApp iOS Fatal App Hang at main (generic main-thread hang)

Evidence chain:

1. iOS watchdog kills the app after 2000ms main-thread block
2. The blocked frame is ComponentDescriptorRegistry::findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN
3. This function is called from AnimatedMountingOverrideDelegate::pullTransaction (for each animated mutation) and RCTSurfacePresenter (for synchronous view updates)
4. The function acquires shared_lock(mutex_) — blocks when add() holds unique_lock on the same mutex
5. add() is triggered by Fabric interop lazily registering legacy view managers — more likely in HybridApp which bridges OldDot components
6. The entire mount pipeline (calculateShadowViewMutations → animated override → native mutations) runs under a scoped_lock on MountingCoordinator::mutex_, compounding the blocking time

Impact: ~36 users over 14 days, iOS HybridApp only. Fatal (watchdog termination).

Confidence: High — the mutex contention mechanism is clearly visible in the RN source code, and the HybridApp + Fabric interop combination creates the conditions for contention.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @jayeshmangwani (External)

[melvin-bot]

Unable to auto-create job on Upwork. The BZ team member should create it manually for this issue.

[KJ21-ENG]

🚨 Edited by proposal-police: This proposal was edited at 2026-05-21 11:58:04 UTC.

Proposal

Please re-state the problem that we are trying to solve in this issue.

iOS HybridApp users are hitting a fatal app hang while React Native Fabric is mounting or updating views. The main thread spends more than the watchdog budget in Fabric's component descriptor registry and iOS terminates the app.

What is the root cause of that problem?

The app ships React Native 0.83.1 and enables the iOS new architecture/Fabric path:

App/package.json

Lines 161 to 162 in c8af8b3

	"react-native": "0.83.1",
	"react-native-advanced-input-mask": "1.4.6",

App/ios/Podfile

Lines 81 to 84 in c8af8b3

	# ENV Variable enables/disables TurboModules
	ENV['RCT_NEW_ARCH_ENABLED'] = '1';
	# ENV Variable enables/disables Hermes V1
	ENV['RCT_HERMES_V1_ENABLED'] = '1';

The Sentry frame is a Fabric registry read:

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/componentregistry/ComponentDescriptorRegistry.cpp#L116-L127

That method is named DO_NOT_USE_THIS_IS_BROKEN, but the hang mechanism is the registry locking around legacy/Fabric interop descriptor registration. RN 0.83.1 constructs component descriptors while holding registry locks. ComponentDescriptorProviderRegistry::add() holds the provider-registry mutex while it calls each registry->add(provider), and ComponentDescriptorRegistry::add() then holds its own unique lock while it runs the descriptor constructor:

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/componentregistry/ComponentDescriptorProviderRegistry.cpp#L12-L41

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/componentregistry/ComponentDescriptorRegistry.cpp#L31-L50

For iOS legacy view-manager interop, that constructor can look up a legacy view manager through the bridge/bridge proxy:

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/components/legacyviewmanagerinterop/LegacyViewManagerInteropComponentDescriptor.mm#L94-L101

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/components/legacyviewmanagerinterop/LegacyViewManagerInteropComponentDescriptor.mm#L139-L152

That lookup may synchronously require main-thread work for ObjC modules/view managers. At the same time, the Fabric mount/update path on the main thread reads the same descriptor registry from call sites such as UIManagerUpdateShadowTree, AnimatedMountingOverrideDelegate, and RCTSurfacePresenter:

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/uimanager/UIManagerUpdateShadowTree.cpp#L168-L177

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/ReactCommon/react/renderer/animated/internal/AnimatedMountingOverrideDelegate.cpp#L70-L81

https://github.com/facebook/react-native/blob/541213e85519d3cc5b9a84f0990a88654b4a1a94/packages/react-native/React/Fabric/RCTSurfacePresenter.mm#L164-L178

So the deadlock/hang is:

1. JS/background registration enters ComponentDescriptorRegistry::add(), holds the registry unique lock, and constructs a legacy interop descriptor.
2. That descriptor construction synchronously waits for the main thread through bridge/view-manager lookup.
3. The main thread is already in a Fabric transaction and tries to take a shared registry lock from findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN.
4. The main thread waits for the registry lock, the registration thread waits for the main thread, and the iOS watchdog kills the app.

This matches the upstream RN issue for a ComponentDescriptorRegistry deadlock with legacy interop and main-thread synchronous lookup:

react/react-native#53128

Changing only the findComponentDescriptorByHandle_DO_NOT_USE_THIS_IS_BROKEN call sites to name-based at(name) is not enough. The name-based lookup still takes the same registry shared lock and can also call providerRegistry_.request(...), so it can move the blocked frame without removing the lock inversion.

What changes do you think we should make in order to solve the problem?

Patch React Native 0.83.1 in patches/react-native so descriptor construction and legacy interop lookup do not run while descriptor registry locks are held.

1. In ComponentDescriptorRegistry::add(), construct the ComponentDescriptor before taking mutex_. Then acquire the unique lock only for the _registryByHandle / _registryByName insertion, with a duplicate-handle recheck before overwriting.
2. In ComponentDescriptorProviderRegistry::add(), hold mutex_ only long enough to validate/insert the provider and copy the live component registries to a local vector. Release the provider-registry lock before calling registry->add(provider) for each registry.
3. In ComponentDescriptorProviderRegistry::createComponentDescriptorRegistry(), copy the provider list under the provider-registry lock, register the new weak registry, then release the lock before populating the new registry with registry->add(...).
4. For iOS legacy interop, either enable the RN enableInteropViewManagerClassLookUpOptimizationIOS path or patch LegacyViewManagerInteropComponentDescriptor.mm to avoid lazily instantiating bridge modules just to resolve a view-manager class when RCTGetModuleClasses() can identify the class. This reduces the chance of RCTUnsafeExecuteOnMainQueueSync during descriptor construction.
5. Add the patch as the next available react-native+0.83.1+NNN+fix-fabric-component-descriptor-registry-deadlock.patch entry and document it in patches/react-native/details.md.
6. Add a focused native regression note/test plan: start HybridApp/new architecture on iOS with a legacy interop view manager that requires main-queue setup while a Fabric transaction reads the descriptor registry; the app should not hang. At minimum, run an iOS new-architecture build and verify the patched RN sources apply cleanly.

Scope boundaries: Files touched are limited to the RN patch under patches/react-native, covering ComponentDescriptorRegistry.cpp, ComponentDescriptorProviderRegistry.cpp, and the iOS legacy interop lookup path if needed, plus patches/react-native/details.md. This should not touch app JS screens, HybridApp TurboModule API, OldDot/YAPL bridge code, backend/API contracts, or web/mWeb rendering.

What alternative solutions did you explore? (Optional)

A pure handle-to-name lookup change is incomplete because both lookup paths use the same descriptor registry lock; it can change the symbol shown in Sentry without fixing the deadlock.

Eagerly registering all descriptors at startup may reduce runtime registration, but it still uses the same locked construction path and can reproduce the startup deadlock described upstream. It is safer to remove descriptor construction from the locked section.

Waiting for a React Native upgrade may eventually pick up an upstream fix, but this repo already carries targeted RN patches for production Fabric issues, and this failure is fatal for HybridApp users.

Disabling Fabric/new architecture would route around this path, but it is too broad for a Sentry group isolated to Fabric descriptor registry locking.

[KJ21-ENG]

Updated my proposal - shifted the fix from handle-to-name descriptor lookup to the RN descriptor-registry lock inversion around legacy Fabric interop registration.