Try the Hardware Debugger Troubleshooter page first.
Once completed, there is a selection of Tips below for specific issues, and these will make more sense after following the Troubleshooter.
If you have trouble getting the Hardware debugging, the below list of Error and Tips may help:
NOTE - this does not apply to the "GDB via Software" or "vMicro Serial Debugger" options
Failed to Connect to Debugger
Ensure your project does not have spaces in the name (i.e. is Arduino Compatible)
This can cause issues when passing the parameters through to the debugger in some configurations.
Ensure your sketch is not using any of the Debugging Pins
e.g. on the ESP32 you cannot use pins 12,13,14,15 in your sketch as these are needed solely for debugging.
It has been occasionally seen in VS2019 that the toolsets may not always download automatically.
The toolset archives can be downloaded from the links below manually:
This needs extracting to "C:\Program Data\vMicro\tools\", and after this you should be able to see files in the folder,
E.g. "C:\Program Data\vMicro\tools\openocd-0.10.0.1\bin" folder should be "openocd.exe" and a number of dll files.
The debugger should start once these files are in place, if there are no other issues...
Are all wires connected as directed in the diagrams? Its always worth checking as this will prevent any debugging working.
Is the ribbon cable the right way around?
Example 20 Pin JTAG Ribbon cable with (D)ebugger and (T)arget marked
Example 10 Pin SWD Ribbon cable with (D)ebugger and (T)arget marked
Also check the diagrams from the links on our debugger list here
Do both the debugger and target board show their power LED's when both are connected to the PC and each other as needed?
You may still need to supply additional power to your target (via USB lead or power pins direct)
If they both work until they are connected together, then you have a short somewhere in the connections (check VCC/GND specifically)
Have you installed the manufacturers' drivers?
Did you need to replace the Interface 0 driver? (check the debugger list for your debugger)
To manually check if the debugger is connecting:
- Open the Output Window and select "Show Output From: Debug"
- Select the first command (everything after 'Starting: ')
- Open a new command line (cmd.exe)
- Paste in the command and run it
- Inspect the output
If you see output similar to above "unable to open device with vid" then check your driver, and any additional driver installation
Black Magic - You need to select a different port in vMicro to connect to the debugger compared to your board, if not using the debugger to perform the upload.
All other debuggers are identified via a mechanism which does not require a COM port, but relies on the drivers installed (see above)
Code Upload to Board
If you see the below message, that you have "Debug" configuration selected at the top of the IDE, and you have uploaded your code to the board
If the code is definitely uploaded, and IDENTICAL to what you are debugging, just perform a build, and then attach.
One reason you see the below if all drivers, and connections between your boards and the PC are OK, but the connections between the debugger and the target are failing.
ESP32 - Missing TDI Wire Connection
The example below is for an ESP32 with a Segger J-Link, and will appear as below if the TDI wire is not connected (pin 12 on your ESP32)
Swapping Without Re-Powering
If you are swapping between a variety of targets and debuggers within a session, ensure you power down both the debugger and the target before changing the connections. This ensures that everything works as expected when re-powered, and no previous running configurations can conflict.
If the debugger starts and connects, but you never land on your breakpoint..... stop the session, and reboot the target board using its reset button. Try connecting the debugging session again, it should now work as expected...
Cannot Upload and Debug
In some cases you can no longer upload to the target via serial when the debugger is connected.
In this scenario, unplug one end of the ribbon cable (or JTAG connections), perform the serial upload, then attach it again.
Then press "Debug" > "Attach To Process"
Further information will be added to this page as it is identified, so do check back with us....