LLD:HowToDebug

This document tries to list out the key ways to debug Ledger Live Desktop (LLD).

LLD is an Electron app that have 3 processes: the main process (which initialise the app and create the window), the internal process (which runs the USB stack in a Node.js-like environment) and the renderer process (which runs 99% of the logic of the app as well as the UI, as it's basically running with Chromium).

Each kind of bug may requires different approach and it will require you to first identify where you need to investigate (on which process).

How to access logs / general way to investigate things

Ledger Live produces logs that can be useful to understand the state and behaviour of a Ledger Live instance. We may ask users to "export the logs" to also be able to put ourself in the foot of the user. There are therefore two kinds of logs investigation:

• as a developer, you want to see the logs in real time. to do so you must run the app with VERBOSE=1 (note that you can also have finer level of filtering, see https://github.com/LedgerHQ/ledger-live/pull/4709 ). You can then use Chromium Dev Tools

  • in dev mode. You can Right Click > Inspect Element
  • in production mode (but also works in dev mode) you will also need to run the app with DEV_MODE=1 to force the opening of dev tools at boot.

• as a user, you want to export the logs at a specific time and be able to provide to engineers a way to investigate something.

  • you can do so at any point in time using Ctrl+E. Some in-app button can also appear to do the same action (typically in context of a crash)
  • Once you have saved the associated text/json file, it can be opened with https://live.ledger.tools/logsviewer . The tools offer useful feature like: the ability to see the logs, the ease to export the APDU (binary exchange with the device), the ability to recompose a "app.json" to facilitate an engineer to open Ledger Live with similar user data.

• ELECTRON_ENABLE_LOGGING=1 can also be used to display logs from renderer directly on the terminal.

How to debug: "Ledger Live window never appears"

If Ledger Live window never appears, you are possibly looking at a bug in ledger-live-desktop/src/main. you will want to look at the Terminal logs. you need to deeply look at the logs from your console after running pnpm lld:dev. If it's on a Release, you also will need to run the binary with the terminal (for instance on Mac, you run /Applications/Ledger\ Live.app/Contents/MacOS/Ledger\ Live on a terminal)

Still stuck in dev mode? You may want to comment out show: false, in window-lifecycle.ts to force the appearance of the window straight from the beginning before a possible failure to eventually .show() it.

How to debug: "Ledger Live never loads, splash screen forever"

If Ledger Live window keep showing you a spinner and never loads, you are possibly looking at a bug in ledger-live-desktop/src/renderer init scripts. It can mean anything but basically the JavaScript boot scripts likely have an error (a library critically fail to load, a syntax error somewhere, issues in the root components, etc..). you will want to look at the Chromium Dev Tools logs (run again with DEV_TOOLS=1 and look at the console). If you didn't change anything, you can try to clean and rebuild the app, or reset the user data folder (corrupted app.json?)

How to debug: "Ledger Live's USB never works" / internal process related issues

If Ledger Live never manages to connect to a device over USB, you are likely looking at an Internal process bug. A trivial way to reproduce it is to mess up with the "usb" library (like something failed to compile it), so if this happens in dev mode, you may want to first try a clean and rebuild of LLD. Thanks to https://github.com/LedgerHQ/ledger-live/pull/4709, you should be able to access logs from internal process by directly looking at the logs.

If this is not enough, you can also try to inspect into the internal process:

• Start the app with DEV_TOOLS=1 LEDGER_INTERNAL_ARGS=--inspect OR even better with DEV_TOOLS=1 LEDGER_INTERNAL_ARGS=--inspect-brk
• Open your Chrome browser on chrome://inspect in the search bar
• in the dev tools, you should see an entry for the Ledger Live internal process script. Click "Inspect".
• a new dev tools window should open and you will be able to see all the logs. (NB: if you use the inspect-brk you will have to "Start" the process, and this is how you can also see the initial logs in case of a very bad crash)
• see official doc for more information: https://nodejs.org/fr/docs/guides/debugging-getting-started

How to debug a Ledger Live production instance with sourcemap on

When trying to understand why a production app badly crashes and when you can't reproduce "locally" in dev mode, your only remaining way is to debug the production app itself. In that case, you first want to try the solution shared above (like export logs). But you can also try to "breakpoint" / "pause on exception" into the JavaScript code. If you follow that path, you will face a difficulty: our builds have JavaScript minified which makes it unreadable. To solve this, you need the JavaScript sourcemaps, they are big so we don't include them in production builds, but you can simply find a build similar to the one you met the issue at https://download.live.ledger.com/ (NB: today release and prerelease don't have sourcemaps, but custom builds and nightly builds do)