ledger-live: Skill for Claude Code

Debug RN native crash

Trigger

The mobile app crashes with one of:

• A native iOS exception (NSInternalInconsistencyException, RCTFatal, Fabric assertion)
• Only a native stack trace (RCTViewComponentView, RCTPerformMountInstructions, …) with no JS source
• "Failed to symbolicate" in Metro and no actionable JS error
• Reproducible crash but unclear which RN component is at fault

If the JS console already gives a clear stack, don't use this skill — read the JS error.

Workflow

1. Capture the native exception from the simulator

xcrun simctl list devices booted   # get the booted sim UDID
xcrun simctl spawn <UDID> log show --last 5m --style compact \
  --predicate 'processImagePath CONTAINS "ledgerlivemobile" AND (eventMessage CONTAINS "Assertion failure" OR eventMessage CONTAINS "Attempt to unmount" OR eventMessage CONTAINS "Terminating app")'

Extract the exception message, native stack, and any view descriptors (frame, tag, backgroundColor, alpha). These already tell you a lot — see reference.md "Anatomy of a Fabric assertion message".

2. Reproduce under Xcode debugger

open apps/ledger-live-mobile/ios/ledgerlivemobile.xcworkspace

• Stop the running app first (otherwise Xcode can't attach cleanly).
• In Xcode: Cmd+8 → + → Exception Breakpoint → Objective-C → All.
• Cmd+R to build + run + attach.
• Reproduce the crash. Xcode pauses at objc_exception_throw.

3. Identify the offending React component

In the lldb console at the bottom of Xcode:

1. Pick the frame that has the offending C++/ObjC code:

   bt              # full backtrace, find the frame in RN code
   frame select N  # N = the RN frame (often RCTPerformMountInstructions)
   

2. Inspect the views referenced by the failed instruction. Variable names depend on the frame — read the source displayed in Xcode. Common ones:

   po parentViewDescriptor.view
   po oldChildViewDescriptor.view
   p  mutation.parentTag
   p  mutation.index
   p  oldChildShadowView.componentName
   

3. Find where the orphan child is actually attached vs where Fabric thinks:

   po [oldChildViewDescriptor.view superview]
   po [oldChildViewDescriptor.view accessibilityIdentifier]   # = RN testID
   po [parentViewDescriptor.view superview]
   po [[parentViewDescriptor.view superview] accessibilityIdentifier]
   po [parentViewDescriptor.view subviews]
   

4. Climb the superview chain until you hit a accessibilityIdentifier (= RN testID) you recognise in source. Grep for it:

   grep -rn 'testID="<identifier>"' apps/ledger-live-mobile/src libs/ui
   

   That's the RN component family. From there, read the JSX and find the conditional render / animation / library that produced the mismatch.