Debugger can't connect to a new board over SWD

The board is assembled. The probe is plugged in. The programming tool says “no target found” or “failed to connect,” and the one thing you need, a way to talk to the chip, is gone. Sometimes it worked once and then stopped. Sometimes a second board does the same thing.

This is almost always one of five causes, and they can be told apart in a few minutes with a multimeter and a probe setting. Work through them in this order, because the early ones are cheap and the late ones are destructive.

1. The probe can’t see the target’s voltage

Most debug probes do not power the target. They measure the target’s supply on a reference pin and use it to set their signal levels. SEGGER’s J-Link troubleshooting article describes the failure directly: the probe measures 0 V on its target reference pin, and that reference is mandatory because it sets the debug signal levels.

So before anything clever:

• Confirm the board is actually powered, at the chip’s pins, not only at the connector.
• Confirm the probe’s reference pin lands on the same rail as the chip’s I/O supply. On a board with a level-shifted or isolated rail, it is easy to wire it to the wrong one.
• Confirm ground is common between probe and board. A long ribbon with one ground wire is a classic source of intermittent connections.

2. The wiring is wrong, shared, or too fast

Swapped SWDIO and SWCLK is the most common wiring error on a first spin, and it is invisible in a schematic review if the connector footprint was drawn mirrored. Check the connector pinout against the probe’s pinout, pin by pin, and ring out each signal to the chip pad.

Two quieter problems:

• The debug lines are shared. SEGGER lists signals shared with other peripherals, or with an on-board emulator, as a cause of failed connections. A pull-up, an LED, or a sensor on a debug pin can load the line.
• The link is too fast for the wiring. SEGGER suggests reducing the interface speed as a first test. A slow clock rules out marginal signal quality from long leads or a poor connector before you touch the design.

If a slow clock connects and a fast one doesn’t, the board is telling you something about the debug connector’s routing. That matters for production, where the fixture cable is never as short as the bench cable. Our note on test points and programming pads covers where those pads should go.

3. The firmware is hiding the chip

This is the cause that surprises people, because the board connected fine on the bench and now doesn’t. A chip that is running your code can make itself unreachable in three ways:

1. The application reassigns the debug pins to something else, such as GPIO or a peripheral.
2. The application disables the debug interface on purpose.
3. The application enters a low-power mode in which the debug connection is dropped.

SEGGER names the second and third explicitly: the application may “disable the debug interface” or enter some kind of low-power mode, either of which can block a connection. Their suggested prevention is a deliberate delay at the start of the application, long enough for the probe to halt the processor before the risky code runs.

Many MCU families have a debug-in-low-power control, often in a debug MCU register, that keeps the debug block alive during sleep, at the cost of higher current. The bit names and behavior differ by family, so read the debug chapter of your exact part’s reference manual rather than carrying settings over from another family. And remember the trade-off: a board that sleeps happily with the debugger enabled may draw more than the real product will. We cover the measuring side in why sleep current beats the datasheet.

4. Connecting under reset

The standard answer to a hiding chip is to hold the chip in reset while the probe attaches, so the debugger arrives before the firmware has a chance to reconfigure anything. OpenOCD documents this as the connect_assert_srst setting in its reset configuration: it asserts the system reset line before connecting. Its documentation notes that only some targets support the feature, with STM32 as an example, and it requires the reset line to be declared as wired and usable while debug commands are issued.

Two consequences for hardware:

• The reset line has to be on the debug connector and wired to the chip. If nothing connects the probe’s reset pin to the MCU’s reset pin, connect-under-reset silently does nothing. Boards that drop the reset pin from the header to save a pad are the ones that cannot be recovered after a bad firmware image.
• A reset supervisor or a large capacitor on the reset net can fight the probe. If the probe can’t pull the line low cleanly, or the net is held by another driver, the reset never reaches the chip. Check the reset net with a scope while the probe asserts it.

Most commercial probes and tools offer the same behavior as a setting, often called “connect under reset” or “hardware reset.” Turn it on before you assume the chip is dead.

5. The chip is locked

Read-out protection is meant to stop a debugger. If someone enabled it, whether you, a programming house, or a default in the part, then a debugger that connects at all will find the memory blocked. Recovery means erasing the chip, and that destroys the firmware.

Nordic’s documentation on access port protection is a clear example of how this works. When protection is on, the debugger is blocked from reading and writing CPU registers and memory. The way out is an ERASEALL command through a separate control access port, and the manual says it erases the flash, the user configuration registers, and RAM. The same page notes that on later revisions of the part, protection is enabled by default, while on earlier ones it was off until firmware turned it on. That detail matters when a new batch of the same part number behaves differently from your prototypes. It is the same trap we describe in when a chip revision changes but the part number doesn’t.

Other vendors use different names and different recovery paths, and some options are one-way. Before you run a mass erase or a “recover” command:

• Confirm that the chip is locked, not just unreachable. Steps 1 to 4 must fail first.
• Confirm that you have the source for what is on it. A mass erase on the only copy of a customer’s firmware is a bad afternoon.
• Confirm that your production flow doesn’t re-lock the chip as a side effect. If it does, recovery fixes one board and the next one arrives locked again.

What to put on the board so this never costs a day

The fix for most of the above is in the layout, decided before the board is ordered:

• Put SWDIO, SWCLK, the reset line, ground, and the target voltage on the programming header, every time.
• Keep the debug lines clear of other loads, and let nothing in the application take over those pins by accident.
• Leave the reset net simple enough that a probe can pull it low.
• Reserve the ability to erase and reprogram a locked board without desoldering anything, because the first board that needs it will arrive at the worst moment.
• Plan on firmware that leaves a short window at startup, or an explicit way in, so a sleeping or misconfigured application can always be halted.

Where we come in

We design the programming path in with the board, the header, the reset net, and the startup window, and we chase a stuck board down from the probe’s point of view. If you have a board that won’t connect, send us the schematic, the programming header pinout, and what the probe reports, and we will tell you which of the five it is.