> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# J-Link debugging

> Connect a SEGGER J-Link, program a debug build, or attach with matching symbols.

Use J-Link to debug a target supported by your installed SEGGER software. A board appearing in Embedder's catalog does not establish J-Link compatibility; verify the exact MCU and probe combination.

## Prepare the host and board

1. Install the SEGGER J-Link software for your host, including J-Link GDB Server. Embedder looks on `PATH` and in common SEGGER installation directories.
2. Connect the probe to the board's debug connector, with the correct signal wiring, ground, and target voltage reference. Power the board and confirm the probe can identify the target.
3. Build an ELF with debug symbols. Use the ELF from the installed firmware when attaching to an existing run.
4. Record the exact SEGGER device name and the board's **SWD** or **JTAG** interface. Close other applications holding the probe.

In the connection settings in [EMBEDDER.md](/core-concepts/embedder-md), use:

```text theme={"system"}
Debug Interface = jlink
```

The device name must come from the installed SEGGER device list; a board name or a nearby MCU name is not a substitute. Ask Embedder to check J-Link readiness and list the detected probes before connecting.

## Start a debug run

Switch to Debug mode with `/debug`. Give Embedder the artifact, device name, and interface:

```text theme={"system"}
Use the connected J-Link and the exact SEGGER device name recorded in
EMBEDDER.md. Program build/app.elf over SWD, run to main, then show the
current frame and registers. Report the selected device before starting.
```

Replace `build/app.elf` and the interface with your project's values. A successful programming connection loads the ELF and attempts to stop at `main`. Check the reported stop location; a missing symbol or timeout does not establish that the intended code ran.

You can then request breakpoints, stepping, stack frames, variables, registers, or memory. See [Common debugger workflow](/debug-mode/gdb).

## Attach to existing firmware

The normal connection programs the ELF. Request **attach-only** to load symbols without programming or running to `main`. Request **no halt** separately if the target should keep running.

```text theme={"system"}
Attach through J-Link using build/app.elf for symbols only. Do not program
or run to main. Check whether this target setup permits no-reset, no-halt
attachment before connecting; preserve the current fault state.
```

Disabling run-to-main alone still permits programming. On a programming connection, requesting no halt causes Embedder to reset and halt after loading the ELF. Follow the [attachment precautions](/debug-mode/gdb#attach-to-a-running-target); probe startup can still affect execution.

## RTT and probe sharing

Use [RTT](/debug-mode/rtt) for firmware output through J-Link. The standard debug connection enables RTT support, but the firmware must provide RTT channels. Starting a debugger can take over a probe used by an existing RTT session; check the active connection after switching workflows.

When finished, tell Embedder whether to leave the firmware running or halted, then disconnect the debugger. Stop competing sessions before starting another probe operation.

## Troubleshoot

* **J-Link GDB Server not found:** install the complete SEGGER package or put its executable directory on the environment's `PATH`, then reopen Embedder.
* **Unknown device:** check the exact SEGGER name and whether your installed package supports it.
* **Cannot connect:** check target power, voltage reference, wiring, SWD/JTAG selection, and competing probe users.
* **Wrong source or missing variables:** use matching symbols and check optimization settings.
* **Run-to-main fails:** verify the entry path and `main` symbol, then inspect the actual stop reason before continuing.