GDB Cannot Connect to PICSimLab on localhost:1234? Backend Fixes

You started your GDB, typed target remote localhost:1234, and got a refusal — or worse, a silent hang. In PICSimLab, remote GDB debugging only exists for some backends, only after you switch it on inside the simulator, and only with the matching GDB flavour for your chip family. This page sorts all three conditions, backend by backend.

Symptoms

  • target remote localhost:1234 (or target extended-remote localhost:1234) fails with “connection refused”.
  • The wrong GDB binary connects oddly, errors immediately, or cannot make sense of the target.
  • You cannot find any GDB option for your board at all — notably on the uCboard or the gpboard.
  • Debugging worked in MPLAB X but the command-line GDB flow does not (or the reverse).

Why it happens

Debug was never enabled in PICSimLab. The shared pattern in the official documentation for every GDB backend is: first open PICSimLab’s configuration window, enable debug and select GDB, and only then connect. With debug off, nothing listens on port 1234 and every connection is refused — the most common cause by far.

Each backend has its own debugger. There is no single “PICSimLab GDB”. Per the official Boards/backend documentation:

Backend (boards)Remote debug interface
simavr (Arduino Mega / Nano / Uno, Franzininho DIY)avr-gdb — plus MPLAB X integrated debug
qemu-stm32 (Blue Pill, STM32 H103)arm-gdb (arm-none-eabi-gdb or gdb-multiarch)
qemu-esp32 (ESP32-DevKitC, ESP32-C3-DevKitC-02)esp32-gdb (xtensa-esp32-elf-gdb)
picsim (the PIC boards)MPLAB X integrated debug — not remote GDB
uCsim (uCboard: C51 / Z80 / STM8S103)Remote console over telnet — not GDB
gpsim (gpboard)None yet — no debugging support

So two “failures” are actually correct behaviour: pointing GDB at a uCboard can never work (its remote debug is a telnet console), and the gpboard has no debugging support yet at all. Two port traps complete the picture: the MPLAB X plugin also uses port 1234 (a separate path — running both at once invites a clash), while PICSimLab’s rcontrol interface on port 5000 is not a debug port and GDB cannot talk to it. Finally, the official online version has no debugging support — GDB debugging is a desktop-version feature.

Fix

  1. Confirm your backend is a GDB backend. GDB applies to simavr, qemu-stm32 and qemu-esp32 boards only. For PIC boards, use the MPLAB X path instead (see our MPLAB X plugin guide); for the uCboard, use its telnet console; for the gpboard, run without a debugger.
  2. Load the board and firmware in PICSimLab first, using the desktop version, with the simulation ready.
  3. Enable debug in the configuration window and select GDB (as opposed to any other debug option). This is the step that opens the listener on port 1234.
  4. Start the matching GDB with your .elf file as its argument — avr-gdb for AVR boards, arm-none-eabi-gdb (or gdb-multiarch) for the STM32 boards, xtensa-esp32-elf-gdb for the ESP32 boards — then connect with target extended-remote localhost:1234 (the STM32 documentation uses the extended-remote form; the AVR/ESP32 flows use the same localhost:1234 endpoint). Using the .elf (not the .hex) is what gives GDB your symbols.
  5. If the connection is still refused: confirm the port in the configuration window is actually 1234 (it can be changed), confirm no firewall is dropping the localhost connection, and close anything else holding port 1234 — most often an MPLAB X plugin session — before retrying.
  6. Do not substitute ports. If you find yourself typing port 5000 into GDB, stop: 5000 is rcontrol, the text-command remote control for the simulator itself (start/stop, loadhex, pin inspection). It is a useful tool, but it is not a debug server.

Still stuck?

Cross-check your flow against the MPLAB X plugin guide if your board is a PIC board (that, not GDB, is its debug path), and against a known-good board/firmware combination from the blink tutorial to separate “simulator not running” from “debugger not connecting”. If debug is enabled, the backend and GDB flavour match, and localhost:1234 still refuses on the desktop v0.9.3, report it — backend, board, GDB flavour and the exact GDB error included — on the project’s tracker: github.com/lcgamboa/picsimlab/issues.

Similar Posts