fix: improve Ledger error handling for disconnect, retry, and pagination cp-7.77.0

[dawnseeker8]

Description

Fixes multiple issues with Ledger hardware wallet error handling that caused confusing error dialogs when the device was disconnected, the Ethereum app was closed, or blind signing was disabled:

1. Stale BLE transport cleanup — #closeTransport now forces BLE disconnection even when the transport object is already null but a device ID remains, preventing the OS from keeping a stale connection that blocks reconnection.
2. Broader transient error detection — #isTransientBleError now falls back to message-based matching (e.g. "disconnected", "bluetooth", "gatt") for BLE errors that use generic Error names after a device power-cycle.
3. Wrong-app command failure cleanup — #handleWrongApp now closes the transport when openEthereumAppOnLedger or closeRunningAppOnLedger fails, preventing stale connections.
4. Pagination device readiness — nextPage/prevPage in LedgerSelectAccount now call ensureDeviceReady before fetching accounts, and only dismiss the blocking modal if it was actually shown (via a modalShown flag).
5. Disconnect error classification — getLedgerAccountsByOperation now detects disconnect errors and throws a user-friendly "device got disconnected" message instead of a generic error.
6. Gitignore updates — Added .cursor/hooks/state/ to .gitignore to prevent Cursor IDE state files from being committed.

Changelog

CHANGELOG entry: Fixed Ledger hardware wallet error handling to properly recover from disconnects, app switching failures, and pagination errors

Related issues

Fixes: #28272

Manual testing steps

Feature: Ledger error handling on disconnect

  Scenario: User disconnects Ledger during account pagination
    Given the user has connected a Ledger device via Bluetooth
    And the Ledger Select Account screen is displayed

    When the user disconnects the Ledger device
    And the user taps Next Page
    Then the app should prompt the user to reconnect instead of showing a generic error

  Scenario: User switches apps on Ledger during operation
    Given the user has connected a Ledger device with the Ethereum app open

    When the user switches to a different app on the Ledger
    And an operation is attempted
    Then the app should detect the transient BLE error and retry the connection

  Scenario: Ledger is powered off during account fetch
    Given the user has connected a Ledger device via Bluetooth
    And the Ledger Select Account screen is displayed

    When the user powers off the Ledger device
    And the user taps Next Page or Previous Page
    Then the app should show a disconnect-specific error message
    And the blocking modal should not be incorrectly dismissed

Screenshots/Recordings

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Medium Risk
Changes touch Ledger BLE transport cleanup/retry logic and account-pagination readiness gating, which can affect hardware-wallet connection stability and user flows. Risk is mitigated by expanded unit test coverage across adapter, error parsing, and UI pagination cases.

Overview
Improves Ledger Bluetooth robustness by forcing BLE cleanup even when the transport object is already cleared, and by expanding transient disconnect detection to include message-based matches; it also closes the transport when app-switch commands fail to avoid stale connections.

Updates LedgerSelectAccount pagination (nextPage/prevPage) to call ensureDeviceReady before fetching pages and to only dismiss the blocking modal if it was shown, preventing unnecessary modal flicker and avoiding pagination attempts when the device isn’t ready.

Enhances Ledger error classification by treating disconnect-like failures in getLedgerAccountsByOperation as a user-facing “disconnected” error, and broadens parseErrorByType to handle non-Error objects with Ledger-shaped name/statusCode; adds/updates unit tests across these scenarios.

^{Reviewed by Cursor Bugbot for commit 5e139f5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[nikolastoimenovski-consensys]

Thanks for the feedback @owencraston. Tested on Android and iOS, here is feedback for all the issues:

issue1 - Send trx while the ledger is disconnected:

The “ledger disconnected” error doesn’t appear, but the issue is reproducible only if the user taps “continue” before the Connection Lost screen disappears by itself after turning on the ledger. After that, if the user continues with the scenario, the trx will be success. The video is attached in the slack thread https://consensys.slack.com/archives/C05C8481HSB/p1775639674912209 , since the file size is too big to be attached here.

issue2 - Perform dapp signing while the ledger is disconnected:

The issue is reproducible. Video attached.

101.mov

ISSUE2: [Bug]: [Ledger] "Something went wrong" error is shown when the user tries to perform dapp signing while the ledger ETH “Blind singing” is disabled

Fixed.

ISSUE3: ISSUE3: "Bluetooth required" modal is presented even though the bluetooth is already enabled on both the Mobile and the Ledger device:

The issue is reproducible. Video attached.

102.MP4

ISSUE4: "Ledger disconnected" error is shown on Send/Swap/Bridge/Dapp sign if the user denies to open the ETH app in the first try

Fixed.

ISSUE5: "Unspecified error" message is shown after trying to use the pagination in the Select an Account screen if the ETH app is not open

Fixed.

[dawnseeker8]

Thanks for the feedback @owencraston. Tested on Android and iOS, here is feedback for all the issues:

issue1 - Send trx while the ledger is disconnected:

The “ledger disconnected” error doesn’t appear, but the issue is reproducible only if the user taps “continue” before the Connection Lost screen disappears by itself after turning on the ledger. After that, if the user continues with the scenario, the trx will be success. The video is attached in the slack thread https://consensys.slack.com/archives/C05C8481HSB/p1775639674912209 , since the file size is too big to be attached here.

issue2 - Perform dapp signing while the ledger is disconnected:

The issue is reproducible. Video attached.

101.mov
ISSUE2: [Bug]: [Ledger] "Something went wrong" error is shown when the user tries to perform dapp signing while the ledger ETH “Blind singing” is disabled

Fixed.

ISSUE3: ISSUE3: "Bluetooth required" modal is presented even though the bluetooth is already enabled on both the Mobile and the Ledger device:

The issue is reproducible. Video attached.

102.MP4
ISSUE4: "Ledger disconnected" error is shown on Send/Swap/Bridge/Dapp sign if the user denies to open the ETH app in the first try

Fixed.

ISSUE5: "Unspecified error" message is shown after trying to use the pagination in the Select an Account screen if the ETH app is not open

Fixed.

HI, @nikolastoimenovski-consensys i am unable to replicate the issue 3 in above list. can you clarify whether you have given metamask access bluetooth permission?

[NicolasMassart]

Inline review finding on the new hook test.

[NicolasMassart]

Inline review finding on pagination disconnect classification.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2f9e7f2. Configure here.}

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeAccounts
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 78%

click to see 🤖 AI reasoning details

E2E Test Selection:
All 10 changed files are focused on Ledger hardware wallet functionality:

1. LedgerBluetoothAdapter.ts: BLE transport cleanup fixes - adds closeTransport() on error paths, handles stale connections when transport is already cleared, and expands transient BLE error detection to include message-based matching (not just error name).

2. errors/parser.ts: Robustness improvements - parseErrorByName now accepts unknown type with proper null/type guards, and reorders parsing to check by name before message.

3. useDeviceConnectionFlow.ts: Fixes false "Bluetooth required" errors on startup by only pre-gating transport check when a specific targetDeviceId is set (not in scan mode).

4. Ledger.ts: Adds disconnect error detection in getLedgerAccountsByOperation to surface a specific "ledger disconnected" error message.

5. LedgerSelectAccount/index.tsx: Fixes pagination (next/prev page) to call ensureDeviceReady before showing the loading modal, preventing modal state issues when device is not ready.

Tag Selection Rationale:

• SmokeAccounts is selected because it covers hardware wallet account flows including "adding QR-based hardware wallet accounts" and account management workflows that exercise the Ledger integration path.
• No dedicated Ledger/hardware wallet E2E tests exist in the test suite (confirmed by searching tests/ directory).
• Changes are isolated to hardware wallet BLE/error handling code and don't affect shared navigation, confirmations, or other wallet flows.
• The LedgerSelectAccount view is a navigation route in App.tsx but changes are limited to pagination and device readiness checks.

Confidence note: Confidence is 78 because there are no dedicated Ledger E2E tests in the suite, so SmokeAccounts is the best available proxy for hardware wallet account management coverage.

Performance Test Selection:
Changes are focused on Ledger hardware wallet BLE connection handling, error parsing, and UI state management for the LedgerSelectAccount view. These are bug fixes for error paths and edge cases in BLE connectivity - they do not affect rendering performance, data loading, account list rendering, or any of the critical user flows measured by performance tests. No performance test tags are warranted.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
96.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud