ZXDB Troubleshooting Guide for VS Code

1. Help me understand how debugging works with this extension.

In a nutshell, the extension communicates with the zxdb console program using VS Code Debug Adapter protocol on port 15678. When you launch the zxdb debug extension in VS Code, it opens a new VS Code terminal to launch the zxdb console by using zxdb.command settings (such as ffx debug connect). The zxdb console is in turn connected to a debug agent started on the target device. Once the zxdb console starts, if needed it launches the debuggee program in another VS Code terminal by using the launchCommand configuration (such as fx test hello-world). The extension connects VS Code debugger UI and the zxdb console by forwarding debug configurations, events, exceptions, stacktraces, and process status.

This image shows an architectural overview of zxdb extension as described above.

2. How do I set the ffx path?

The extension should automatically find the appropriate ffx path for your project. see ffx binary path.

3. ffx and/or zxdb does not work in the VS Code terminal.

VS Code shell might have to be configured - See VS Code shell config and shell config for fx.

4. “Timeout starting zxdb console” error.

This image show the timeout error.

This error occurs when the VS Code debugger is trying to connect to the zxdb console and fails. When the Run is clicked, VS Code launches a terminal zxdb console and tries to start the zxdb console. The zxdb console listens on the 15678 port for incoming debug adapter connections. If the VS Code debugger is unable to connect to it within 30 seconds, it throws this error.

Try these steps to resolve the issue:

  • Make sure that the device is up and the package server (like fx serve) is running.
  • Make sure you can connect to your project‘s ffx. If you can’t connect to ffx and have been using the ffx from another project, you may need to run ffx doctor --restart-daemon

5. How to use the zxdb console along with the extension?

Some features of the zxdb console are missing in the UI. Example, inspecting memory with x or as command, disassembly, stepping into assembly code. Since the zxdb console is also launched by VS Code during debugging, it has all the context of the ongoing VS Code debug session and can be used for more advanced debugging.

To start using zxdb console commands, switch to the zxdb console terminal as shown below.

This image shows zxdb console view in VS Code.

Known issues:

  • Bug 80120: Occasionally, Breakpoint hits are not visible in UI

    Workaround: Go to the zxdb console view as shown above and continue debugging. The problem goes away if you stop and start debugging again.