Troubleshooting
Step-by-step fixes for debug probe, SWD and flash programming errors on ARM Cortex-M targets — the same errors MCUHex reports in-app, explained in depth.
SDK & Connection
The local bridge, USB probes and getting a stable link to your board.
SDK not running
The MCUHex SDK server is not reachable.
Read the full guideConnection lost
The connection to the SDK server was dropped.
Read the full guideNo devices found
The SDK is running but no debug probes were detected.
Read the full guideNo device selected
Please select a device before connecting.
Read the full guideDevice is busy
Another tool or debugger is connected to this device.
Read the full guidePermission denied
Your OS is blocking access to the USB device.
Read the full guideProbe driver mismatch
The selected probe driver does not match the connected hardware.
Read the full guideConnection timed out
The device did not respond in time.
Read the full guideDevice disconnected
The USB device was removed during the session.
Read the full guideMemory operation failed
Could not read or write to the device memory.
Read the full guideCommand timed out
The SDK server did not respond to a command in time.
Read the full guideConnection error
An unexpected error occurred.
Read the full guideCortex-M & SWD
Target-side failures: locked debug ports, SWD faults, resets and HardFaults.
Debug port locked
The target debug port is secured (RDP or APPROTECT is active).
Read the full guideSWD protocol error
A wire-level fault occurred on the SWD/JTAG interface.
Read the full guideTarget held in reset
The target MCU is being held in reset and cannot communicate.
Read the full guideTarget not halted
The target is running and memory cannot be accessed safely.
Read the full guideFlash write protected
The target flash region is write-protected.
Read the full guideUnsupported target
The connected MCU is not recognized by the probe driver.
Read the full guideHardFault detected
The target MCU has entered a HardFault exception.
Read the full guideFlash & Files
Firmware programming, verification and file selection problems.
File not found
The selected firmware file does not exist on the SDK host.
Read the full guideUnsupported file format
Only .hex, .bin, .elf, and .axf firmware files are supported.
Read the full guideFlash verification failed
The programmed data does not match the source file.
Read the full guideFlash in progress
Another flash operation is already running.
Read the full guideProbe not connected
Connect to a debug probe before flashing.
Read the full guideFlash cancelled
The flash operation was cancelled.
Read the full guideTarget memory map unknown
PyOCD could not determine the flash region for this MCU. The target was probably auto-detected as generic Cortex-M without a memory map.
Read the full guideFlash programming rejected
The flash controller rejected a page write (PGSERR). Usually this means the target is running, write-protected, or requires a full chip erase before re-programming.
Read the full guideAccess denied
Cannot read the requested directory.
Read the full guideInvalid path
The requested path does not exist or is not a directory.
Read the full guideELF & Debug Symbols
Getting your build’s symbols into MCUHex: file formats, size limits and uploads.
Invalid file type
Only .elf and .out files are supported.
Read the full guideFile too large
Files must be under 50 MB.
Read the full guideParsing failed
The file could not be parsed for debug symbols.
Read the full guideParsing timed out
The server took too long to process this file.
Read the full guideUpload failed
The file could not be uploaded to the server.
Read the full guideConnection error
Could not reach the server.
Read the full guideSign in required
You need to sign in to upload and parse files.
Read the full guideSomething went wrong
An unexpected error occurred.
Read the full guide