STM32CubeProgrammer not found under macOS

[MaJerle]

Please make you search through our existing issues (both open and closed)

It may help to look at these instructions in Preview mode. Please visit the correct repo to file an issue. If this is an issue with

• Peripherals/SVD Viewer: https://github.com/mcu-debug/peripheral-viewer
• Memory Viewer: https://github.com/mcu-debug/memview
• RTOS Viewer: https://github.com/mcu-debug/rtos-views
• the debugger itself, continue below

Please read our documentation as well. You have a lot of control over how Cortex-Debug works. Besides the top level README.md, we have the following

https://github.com/Marus/cortex-debug/wiki
https://github.com/Marus/cortex-debug/wiki/Cortex-Debug-Under-the-hood
https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md

Finally, make sure all your external tools are configured properly and working. We print all the commands in the Debug Console. Most of the bug reports are from Linux users with improperly installed GNU tools. If you can't run those tools, neither can we.

Thank you for helping reduce the number of issues which is becoming overwhelming as most of them are not issues at all. You can delete all the above text and start filing the issue

Describe the bug
A clear and concise description of what the bug is.
To Reproduce
Steps to reproduce the behavior:

1. Move from working Windows to macOS. The launch variables for server, and stm32cubeprogrammer shall be omitted.
2. Install the STM32CubeCLT
3. Install the cortex-debug
4. The STM32CubeProgrammer wont be found.

Expected behavior

STM32CubeProgrammer to be found automatically.

Screenshots

The path being looked at:
/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin

The actual path where I have the CubeProgrammer CLI tools:
/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/Resources/bin/

Environment (please complete the following information):

• Cortex-Debug Version (this extension) [e.g. 0.2.3] - latest preview
• OS: [e.g. Linux Ubuntu 18.04 LTS, Windows 11, etc.] . macOS 26.4.1 M5
• GDB Version: [e.g. 1.11.1] - stlink server from the STM32CubeCLT
• Compiler Toolchain Version: [e.g. arn-none-eabi V 11.1] GCC v15

Please include launch.json

This is the exact launch that works under Windows.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Microcontroller - ST-Link",
            "cwd": "${workspaceFolder}",
            "type": "cortex-debug",
            "executable": "${command:cmake.launchTargetPath}",
            "request": "launch",                //Use "attach" to connect to target w/o elf download
            "servertype": "stlink",
            "device": "STM32G0B1",            //MCU used, ex. "STM32H735IG"
            "interface": "swd",
            "serialNumber": "",
            //"serialNumber": "0024002C3331510733323639", //Set ST-Link ID if you use multiple at the same time
            //"serialNumber": "0028001F3756501620303658", //Set ST-Link ID if you use multiple at the same time
            "runToEntryPoint": "main",
            "svdFile": "../../svd/STM32G0C1.svd",
            "v1": false,
            "showDevDebugOutput": "both",

            /* Will get automatically detected if STM32CubeIDE is installed to default directory
               or it can be manually provided if necessary.. */
            //"serverpath": "/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/Resources/bin/STM32_Programmer_CLI",
            //"armToolchainPath": "c:\\ST\\STM32CubeIDE_1.7.0\\STM32CubeIDE\\plugins\\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.win32_2.0.0.202105311346\\tools\\bin",
            //"stm32cubeprogrammer": "/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/Resources/bin/",

            /* If you use external loader, add additional arguments */
            //"serverArgs": ["--extload", "path/to/ext/loader.stldr"],
        }
    ]
}

Note: We are unlikely to look at the issue if you do not supply this

Paste launch.json contents here

Attach text from Debug Console

Please enable debug output in your launch.json ("showDevDebugOutput": "raw"). It this is too large, please attach it as a file

Paste Debug Console contents here

Additional context
Add any other context about the problem here.

[MaJerle]

My recommendation is to extend the path scope to find the CLI executable.

[haneefdm]

We did this already. We look for the CLI version. It is not clear what version you are using.

https://github.com/Marus/cortex-debug/releases

If you think our logic is wrong, please look at https://github.com/Marus/cortex-debug/blob/master/src/stlink.ts

[MaJerle]

Thanks for the answer. I went deeper, because originally I had installed STM32CubeProgrammer separately. Now if I restart and install only STM32CubeCLT (version 1.21.0), then my STM32CubeProgrammer gets installed:

/opt/ST/STM32CubeCLT_1.21.0/STM32CubeProgrammer/bin

And this one is not auto picked up by the tool. I must manually write this path in the launch.json.

The tool is looking at /Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin

[haneefdm]

We always prefer the CLT versions over anything else. This was a painful decision and did not know what else to do. Is this not working?

If I have bot CLT and IDE installed, and not settings/launch.json properties are used, then I see this.

Launching gdb-server: /opt/ST/STM32CubeCLT_1.20.0/STLink-gdb-server/bin/ST-LINK_gdbserver -p 50000 \
    -cp /opt/ST/STM32CubeCLT_1.20.0/STM32CubeProgrammer/bin --swd --halt

We don't understand ST logic of what is being installed where and can't keep up. We try to auto-discover for ST and no other gdb-server. Every time we add support for their latest, the ground shifts again. Is there a document or something we can follow that tells us authoritatively what rules to follow and for each OS.

You get the best results ALWAYS by using your own settings or properties in launch.json.

I am still not sure what is not working for you though? Please close the issue or clearly explain your situation and what you are expecting.

[MaJerle]

Let me rephrase. I am testing on macOS, 26.4.1 Tahoe (under Windows all works fine) and I have installed the STM32CubeCLT v1.21.0.

When I try to launch the debug session application, without providing any path, I get an error that STM32CubeProgrammer is not available.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Microcontroller - ST-Link",
            "cwd": "${workspaceFolder}",
            "type": "cortex-debug",
            "executable": "${command:cmake.launchTargetPath}",
            "request": "launch",
            "servertype": "stlink",
            "device": "STM32G0B1",
            "interface": "swd",
            "serialNumber": "",
            "runToEntryPoint": "main",
            "svdFile": "../../svd/STM32G0C1.svd",
            "v1": false,
            "showDevDebugOutput": "both",
        }
    ]
}

Debug console shows:

Launching gdb-server: ST-LINK_gdbserver -p 50000 -cp /Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin --swd --halt

The error is

[2026-04-15T06:53:39.136Z] SERVER CONSOLE DEBUG: onBackendConnect: gdb-server session connected. You can switch to "DEBUG CONSOLE" to see GDB interactions.
ST-LINK_gdbserver -p 50000 -cp /Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin --swd --halt
ERROR: Couldn't locate STM32CubeProgrammer in '/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin', use -cp <path>  
[2026-04-15T06:53:39.154Z] SERVER CONSOLE DEBUG: onBackendConnect: gdb-server session closed
GDB server session ended. This terminal will be reused, waiting for next session to start...

My path that cortex-debug tries to use for CubeProg CLI is different than yours. I do not know why.

[haneefdm]

First, what version of cortex-debug are you using? Unless you install the pre-release (see link above) you will not get the CLT versions. I also use the CLT version on my Mac (see post above)

[MaJerle]

It was 1.12.x even if preview was enabled. I've manually installed now the 1.13.prerelease and it works.

Sorry, my bad. Thanks for your help.

[haneefdm]

Next time, please include the contents of the Debug Console (with showDevDebugOutput enabled). It would have saved some time for both of us