launch.json Properties Reference

This document provides a complete, flattened list of all properties supported in your .vscode/launch.json configuration for the MCU-Debug debug adapter.

Understanding the Table

• Property Name / Path: The JSON key path of the configuration property. For nested structures (such as hostConfig or rttConfig), properties are flattened (e.g. hostConfig.enabled).
• Type: The expected data type(s) (e.g., string, boolean, number, array, or union types).
• Request Mode: Indicates whether the property applies to a "launch" request, an "attach" request, or "both".
• Default & Description: The default value (if any) and a description of the property.

Property Name / Path	Type	Request Mode	Default & Description
armToolchainPath	string	both	This setting can be used to override the armToolchainPath user setting for a particular launch configuration.
BMPGDBSerialPort	string	both	The serial port for the Black Magic Probe GDB Server.
boardId	string	both	PyOCD Board Identifier. Needed if multiple compatible boards are connected.
breakAfterReset	boolean	both	Default: false Applies to Restart/Reset/Launch, halt debugger after a reset. Ignored if runToEntryPoint is used.
chainedConfigurations   delayMs	number	both	Default: 5 Default delay in milliseconds.
chainedConfigurations   detached	boolean	both	Default: false Related or independent server sessions.
chainedConfigurations   enabled	boolean	both	Default: true Enable/Disable entire set of chained configurations
chainedConfigurations   inherits	array	both	List of properties to inherit from parent.
chainedConfigurations   launches[]     delayMs	number	launch	Default: 5 Delay in milliseconds.
chainedConfigurations   launches[]     detached	boolean	launch	Default: false Related or independent server sessions.
chainedConfigurations   launches[]     enabled	boolean	launch	Default: true Enable/Disable this configuration
chainedConfigurations   launches[]     folder	string	launch	Folder to use for this configuration.
chainedConfigurations   launches[]     inherits	array	launch	List of properties to inherit from parent.
chainedConfigurations   launches[]     lifecycleManagedByParent	boolean	launch	Default: true Are Reset/Stop/Disconnect shared?
chainedConfigurations   launches[]     name	string	launch	Name of launch configuration.
chainedConfigurations   launches[]     overrides	object	launch	Values to override/set in this child configuration.
chainedConfigurations   launches[]     waitOnEvent	string	launch	Default: postInit Wait for an event.
chainedConfigurations   lifecycleManagedByParent	boolean	both	Default: true Are Reset/Stop/Disconnect shared?
chainedConfigurations   overrides	object	both	Values to override/set in this child configuration.
chainedConfigurations   waitOnEvent	string	both	Default: postInit Event to wait for.
cliOptions   logFile	`string	null`	both
cmsisPack	string	both	Path to a CMSIS-Pack file. Use to add extra device support.
configFiles	array	both	OpenOCD/PE GDB Server configuration file(s) to use when debugging (OpenOCD -f option)
cpu	string	both	Default: cortex-m3 CPU Type Selection - used for QEMU server type
cwd	string	both	Directory to run commands from
debugFlags   debugDisassembly	boolean	both	Default: false Show debug output from disassembly operations
debugFlags   disableGdbTimeouts	boolean	both	Default: false Disable GDB command timeouts. Helpful for debugging extension
debugFlags   gdbTraces	boolean	both	Default: false Enable GDB MI trace output. Copy/Paste friendly.
debugFlags   gdbTracesParsed	boolean	both	Default: false Enable parsed GDB MI output. NOT Copy/Paste friendly.
debugFlags   liveGdbTraces	boolean	both	Default: false Enable live GDB MI trace output during polling (only applies to built-in liveWatch/RTT). Can be super verbose.
debugFlags   pathResolution	boolean	both	Default: false Show path resolution when reading symbols
debugFlags   timestamps	boolean	both	Default: false Show timestamps in debug output
debugFlags   vscodeRequests	boolean	both	Default: false Enable VSCode Request/Response trace output
debuggerArgs	array	both	Additional arguments to pass to GDB command line
device	string	both	Target Device Identifier, needed for probe-rs and some other server types. For probe-rs, this can be a chip name (e.g. 'STM32F103C8')
env	object	both	Environment variables defined as key, value pairs to set for the GDB Server process.
envFile	string	both	Path to a file to read environment variables from for the GDB Server process. The file should have lines in the format KEY=VALUE.
executable	string	both	Path of executable for symbols and program information. See also loadFiles, symbolFiles
gdbInterruptMode	string	both	Default: exec-interrupt Whether GDB shall be interrupted using "exec-interrupt" (default) or by signaling "SIGINT"
gdbPath	string	both	This setting can be used to override the GDB path user/workspace setting for a particular launch configuration.
gdbTarget	string	both	For externally (servertype = "external") controlled GDB Servers you must specify the GDB target to connect to.
graphConfig	array	both	Description of how graphing can be done.
hardwareBreakpoints   limit	number	both	Default: 0 If limit > 0, enforce a limit on the number of hardware breakpoints that can be used
hardwareBreakpoints   require	boolean	both	Default: false If true, forces the use of hardware breakpoints
hardwareWatchpoints   limit	number	both	Default: 0 If limit > 0, enforce a limit on the number of hardware watchpoints that can be used
hardwareWatchpoints   require	boolean	both	Default: false If true, forces the use of hardware watchpoints
hostConfig   enabled	boolean	both	Default: false Enable/Disable remote probe support. When true, the gdb-server runs on a host machine that has the USB debug probe attached.
hostConfig   sshHost	string	both	Default: mylogin@myserver SSH host for type "ssh". Resolved via ~/.ssh/config, so host aliases, port, jump hosts, and keys are all handled there. Example: "user@lab-server" or an alias defined in ~/.ssh/config.
hostConfig   sshProxyPort	number	both	SSH type only — daemon mode. Port the Probe Agent is already listening on at the lab server. When set, the extension connects to the pre-running agent at this port rather than launching a new one. The SSH -L tunnel is established from a local OS-assigned port to this port. When omitted, the extension launches a new Probe Agent per debug session via SSH and reads the port from its Discovery JSON. Set this when the Probe Agent is started manually or managed by a system service on the probe host.
hostConfig   sshProxyServerPath	string	both	Path to a pre-installed mcu-debug binary on the remote host (e.g. "/usr/local/bin/mcu-debug" or "~/bin/mcu-debug"). When set, the extension skips the automatic binary deployment step entirely and uses this path to launch the Probe Agent. Use this when macOS Gatekeeper, Windows SmartScreen, or lab policy prevents running a freshly-copied executable, or when the binary has already been installed and granted the necessary permissions by other means.
hostConfig   syncFiles     local	string	both	Glob pattern for files to sync, relative to ${cwd}. Example: '*.cfg'.
hostConfig   syncFiles     remote	string	both	Remote path to sync the files to. If not specified, the local path is used.
hostConfig   token	string	both	Override the token used to authenticate with the Probe Agent. Only needed for daemon mode when the token file (~/.mcu-debug/agent.token) is not accessible, or when a fixed lab-policy token is preferred. When omitted, the extension auto-manages the token: it generates one for extension-launched agents, or reads it from the token file for pre-running daemons. Do NOT commit this value to source control — use VS Code user settings or a secrets manager.
hostConfig   type	any	both	Default: auto "auto": extension detects the VS Code remote environment and constructs the correct proxy address automatically. Covers WSL (NAT and Mirrored), Dev Containers, VS Code Remote SSH, and plain local. "ssh": explicit SSH to a separate probe host; requires sshHost.
hostConfig   wslProxyPort	number	both	auto type, WSL NAT mode only. Fixed port for the Probe Agent to bind to on the Windows host. Normally not needed: when the Probe Agent runs for the first time, Windows shows a Security Alert — clicking 'Allow access' creates an application-level inbound rule that permits the executable on any port. Set this only if that prompt was dismissed or blocked, or if group policy restricts inbound rules to specific ports. The extension starts the Probe Agent with --port <N> --host 0.0.0.0 so the WSL guest can reach it via the gateway IP. Not needed for WSL Mirrored mode (Windows 11) where loopback is shared. Ignored for all other auto sub-modes (local, Dev Container, Remote SSH).
interface	string	both	Default: swd Debug Interface type to use for connections (defaults to SWD) - Used for J-Link, ST-LINK and BMP probes.
ipAddress	string	both	IP Address for networked J-Link Adapter
jlinkscript	string	both	J-Link script file - optional input file for customizing J-Link actions.
liveWatch   enabled	boolean	both	Default: false Enable/Disable Live Watch.
liveWatch   samplesPerSecond	number	both	Default: 2 Maximum number of samples per second.
loadFiles	array	both	List of files (hex/bin/elf files) to load/program instead of the executable file.
machine	string	both	Default: lm3s811evb Machine Type Selection - used for QEMU server type
numberOfProcessors	number	both	Default: 1 Number of processors/cores in the target device.
objdumpPath	string	both	This setting can be used to override the objdump path user/workspace setting for a particular launch configuration.
openOCDLaunchCommands	array	launch	OpenOCD command(s) after configuration files are loaded (-c options)
openOCDPreConfigLaunchCommands	array	launch	OpenOCD command(s) before configuration files are loaded (-c options)
overrideAttachCommands	array	attach	Override the commands that are normally executed as part of attaching to a running target.
overrideGDBServerStartedRegex	string	both	You can supply a regular expression to override the output from the GDB Server that is looked for to determine if the GDB Server has started.
overrideLaunchCommands	array	launch	Override the commands that are normally executed as part of flashing and launching the target.
overridePreEndSessionCommands	array	both	Override the commands that are normally executed at the start of ending a debug session (e.g. when stopping debugging).
overrideResetCommands	array	both	Override the commands that are normally executed as part of reset-ing the target.
overrideRestartCommands	array	both	Deprecated: Restart is now handled by VSCode. Change to overrideResetCommands if you use the Reset button.
postAttachCommands	array	attach	Additional GDB Commands to be executed after the main attach sequence has finished.
postLaunchCommands	array	launch	Additional GDB Commands to be executed after the main launch sequence has finished.
postResetCommands	array	both	Commands to be executed after a Reset operation, after the reset is sent to the target.
postResetSessionCommands	array	both	Additional GDB Commands to be executed at the end of the reset sequence
postRestartCommands	array	both	Deprecated: Restart is now handled by VSCode. Change to postResetCommands if you use the Reset button.
postRestartSessionCommands	array	both	Deprecated: Restart is now handled by VSCode and it is the same as Start. If you are using the Reset button, use postResetSessionCommands instead
postStartSessionCommands	array	both	Additional GDB Commands to be executed at the end of the start sequence, after a debug session has already started and runToEntryPoint is not specified.
powerOverBMP	string	both	Power up the board over Black Magic Probe.
preAttachCommands	array	attach	Additional GDB Commands to be executed at the start of the main attach sequence (immediately after attaching to target).
preLaunchCommands	array	launch	Additional GDB Commands to be executed at the start of the main launch sequence (immediately after attaching to target).
preResetCommands	array	both	Commands to be executed prior to a Reset operation, before the reset is sent to the target.
rtos	string	both	RTOS being used. For JLink this can be Azure, ChibiOS, embOS, FreeRTOS, NuttX, Zephyr or the path to a custom JLink RTOS Plugin library. For OpenOCD this can be auto (recommended), FreeRTOS, ThreadX, chibios, Chromium-EC, eCos, embKernel, linux, mqx, nuttx, RIOT, uCOS-III, or Zephyr.
rttConfig   address	string	both	Default: auto Address to start searching for the RTT control block.
rttConfig   clearSearch	boolean	both	Default: true When true, clears the search-string.
rttConfig   decoders	array	both	SWO Decoder Configuration
rttConfig   enabled	boolean	both	Default: false Enable/Disable RTT
rttConfig   polling_interval	`number	null`	both
rttConfig   pre_decoder     args	array	both	Default: ["-e","$\{executable\}"] Arguments to pass to pre-decoder program.
rttConfig   pre_decoder     channels	`array	null`	both
rttConfig   pre_decoder     cwd	string	both	Default: $\{workspaceFolder\} Current working directory for pre-decoder program.
rttConfig   pre_decoder     env	object	both	Additional environment variables for pre-decoder program.
rttConfig   pre_decoder     program	string	both	Default: defmt-print Path to pre-decoder program.
rttConfig   rtt_start_retry	number	both	Default: 1000 Keep trying to start RTT for OpenOCD until it succeeds.
rttConfig   searchId	string	both	Default: SEGGER RTT A string to search for to find the RTT control block.
rttConfig   searchSize	number	both	Default: 16 Number of bytes to search for the RTT control block.
rttConfig   useBuiltinRTT     enabled	boolean	both	Default: true Enable/Disable built-in RTT support
rttConfig   useBuiltinRTT     hostName	string	both	Default: 127.0.0.1 Host name to use for built-in RTT server.
rttConfig   useBuiltinRTT     tcpPort	`number	null`	both
runToEntryPoint	string	launch	Default: main Applies to Launch/Restart/Reset, ignored for Attach. If enabled the debugger will run until the start of the given function.
runToMain	boolean	both	Default: false Deprecated: please use 'runToEntryPoint' instead.
searchDir	array	both	OpenOCD directories to search for config files and scripts (-s option).
serialConfig   enabled	boolean	both	Default: false Enable/Disable serial port bridging. When enabled, the extension creates TCP bridges to physical serial ports for easy access to serial output from the target device.
serialConfig   ports	array	both	List of serial port bridges to expose as TCP ports. Each entry maps a physical serial device to a TCP port that can be connected to for bidirectional communication.
serialConfig   ports[]     baud_rate	number	both	Default: 115200 Baud rate in bits per second.
serialConfig   ports[]     data_bits	number	both	Default: 8 Number of data bits per frame.
serialConfig   ports[]     flow_control	string	both	Default: none Flow control mode. "software" = XON/XOFF, "hardware" = RTS/CTS.
serialConfig   ports[]     input_mode	string	both	Default: cooked Input mode for data sent to the serial port. "raw" = send as-is, immediately, "cooked" = buffer input until Enter is pressed and perform basic line editing (backspace, Ctrl+U to clear line).
serialConfig   ports[]     label	string	both	A label for this serial port bridge, used in the extension UI to identify it. E.g. 'Debug UART'. Optional but recommended when multiple ports are configured.
serialConfig   ports[]     log_file	string	both	Optional file path to log all serial data (both input and output). If not set, no logging is performed.
serialConfig   ports[]     parity	string	both	Default: none Parity checking mode.
serialConfig   ports[]     path	string	both	Serial device path or glob. E.g. /dev/ttyUSB0, /dev/tty.usbserial-, COM3, /dev/serial/by-id/usb-. Optional if serial or vid/pid are specified.
serialConfig   ports[]     pid	string	both	USB product ID in hex (e.g. "0x374b"). Used with vid to identify the device type when serial is unavailable.
serialConfig   ports[]     serial	string	both	USB serial number. Stable across reconnects and reboots — preferred in lab environments with multiple boards of the same type.
serialConfig   ports[]     stop_bits	string	both	Default: one Number of stop bits.
serialConfig   ports[]     vid	string	both	USB vendor ID in hex (e.g. "0x0483"). Used with pid to identify the device type when serial is unavailable.
serialNumber	string	both	J-Link or ST-LINK Serial Number - only needed if multiple J-Links/ST-LINKs are connected to the computer
serverArgs	array	both	Additional arguments to pass to GDB Server command line
serverpath	string	both	This setting can be used to override the GDB Server path user/workspace setting for a particular launch configuration.
servertype	string	both	GDB Server type - supported types are jlink, openocd, probe-rs, pyocd, pe, stlink, stutil, qemu, bmp and external. For "external", please read our Wiki. The executable in your PATH is used by default, to override this use serverpath.
stlinkPath	string	both	Path to the ST-LINK_gdbserver executable.
stm32cubeprogrammer	string	both	This path is normally resolved to the installed STM32CubeIDE or STM32CubeProgrammer but can be overridden here.
svdFile	string	both	This is for 'XPERIPHERALS' window provided by 'mcu-debug.peripheral-viewer'.
svdPath	string	both	This is for 'XPERIPHERALS' window provided by 'mcu-debug.peripheral-viewer' and 'Embedded Tools' Extension from Microsoft.
swoConfig   cpuFrequency	number	both	Default: 0 Target CPU frequency in Hz; 0 will attempt to automatically calculate.
swoConfig   decoders	array	both	SWO Decoder Configuration
swoConfig   enabled	boolean	both	Default: false Enable SWO decoding.
swoConfig   source	string	both	Default: probe Source for SWO data.
swoConfig   swoEncoding	string	both	Default: uart BMP only: SWO encoding data used at the line level.
swoConfig   swoFrequency	number	both	Default: 0 SWO frequency in Hz; 0 will attempt to automatically calculate.
swoConfig   swoPath	string	both	Path name when source is "file" or "serial".
swoConfig   swoPort	string	both	When server is "external" && source is "socket", port to connect to.
symbolFiles	array	both	Array of ELF files to load symbols from instead of the executable file.
symbolFiles[]   file	string	both	Pathname of an ELF file for symbols
symbolFiles[]   offset	`number	string`	both
symbolFiles[]   sections[]     address	`number	string`	both
symbolFiles[]   sections[]     name	string	both	Section name
symbolFiles[]   textaddress	`number	string`	both
targetId	`string	number`	both
targetProcessor	number	both	Default: 0 The processor you want to debug. Zero based integer index. Must be less than 'numberOfProcessors'
toolchainPrefix	string	both	This setting can be used to override the toolchainPrefix user setting for a particular launch configuration. Default = "arm-none-eabi"
v1	boolean	both	Default: false For st-util only. Set this to true if your debug probe is a ST-Link V1.