Troubleshooting

Troubleshooting

Stuck on "Connecting..." / "could not open port" / "Access is denied" Another program has the COM port - close other MeshCore apps, the console bot (Run_Agent.bat) and any second copy of mcIRC. Pressing Connect while it is connecting cancels the attempt. Re-run Scan for devices if the port number changed.

"No response from meshcore node" The node is busy or the wrong firmware is on it. It must be Companion firmware (not Repeater/Room server). mcIRC retries automatically.

RADIO NOT RESPONDING (red warning in the status bar) Three commands in a row got no answer. Update to 2.0 or newer first: older versions held the button of ESP32 boards like the Heltec V3 down through the USB lines, which hibernated the node or opened its rescue console. If it still happens, press the board's reset button or replug it. While it is silent, messages you type are marked NOT SENT, and alerts from the alert addons are kept for up to 30 minutes and sent when it answers. Options > Connect > Restart a silent radio automatically (on by default; pulses the USB reset line after about 2 minutes; only CP210x / CH340 / FTDI boards such as the Heltec V3; at most every 10 minutes and 6 times per session), or Tools > Reset radio via USB... once on request. Native-USB boards (ESP32-S3, nRF52, RP2040) are never reset this way - use their reset button. A node stuck in CLI rescue mode is rebooted out of it automatically; Tools > CLI rescue console... opens that console on purpose.

"Connected" but nothing I send arrives / the status bar says LOW or "not heard" The node answers mcIRC over USB or Wi-Fi but its radio isn't getting messages out - most often a flat battery. Charge it or plug it in. The status bar shows each node's battery and turns red when it's low or when your messages stop being repeated.

Only my own messages show, nothing comes in Update to 2.0.2 or newer and restart mcIRC. Before that, one error (for example closing Options while it was still reading the node) could stop incoming messages, status lines and tool results until a restart, and when several messages arrived at once only the last one showed.

The console alerts bot (Run_Agent.bat) sent all its alerts again after a restart Update to 2.0.8 or newer. The bot remembers what it already announced by reading its log, emergency_agent.log; every 5 MB that log starts a new file, and older versions only read the newest one - so a restart soon after that re-sent every active alert. Now the older files are read too.

Firmware builder: "could not open port" / stuck at "Connecting..." while flashing Boards with the chip's own USB port (Heltec V4, other ESP32-S3 boards): hold PRG (BOOT), tap RST, let go of PRG, choose the new USB port and press Build and flash again. Tap RST after flashing if the board doesn't restart. See MeshCore Tools.

Firmware builder: flashed, but the board is not found on the network Wait a couple of minutes (joining the Wi-Fi takes a while), then check your router's client list for an esp32s3-... / Espressif device. It must be a 2.4 GHz network; a guest Wi-Fi is usually kept apart from your PC. A typo in the password means flashing again.

A sender shows as a hex code like @3ddcdf84 mcIRC only knows the key until it learns the name. It looks in its node memory and asks your radio; it renames the window by itself when found.

Repeater command: "no reply within 8 seconds" Out of range, wrong or missing admin password (use /login), or the command has no reply.

"Unknown contact" / "Unknown destination" Your radio forgot the repeater (350-contact limit). Update to 1.1.2 or newer - mcIRC re-adds it automatically.

Strange boxes or a crash with emoji in replies Update to 1.1.2+ (UTF-8) and 1.1.3+ (colour codes stripped).

Sound Test button is silent Your Windows sound scheme may be "No Sounds" - update to 1.1.4+ (beeps instead). The channel-message event is set to None by default. Custom file needs a .wav path.

The map is a plain plot pip install tkintermapview for the street map.

Linux: "permission denied" on the serial port Add yourself to the serial group: sudo usermod -aG dialout $USER (some distros uucp), then log out and back in.

Linux/macOS: "mcIRC needs Tk" Install Tk for Python (see Getting Started).

Send a bug report with a troubleshooting log Help > Report a bug... (or /bug). Describe what went wrong and which board you use; the window shows exactly what will be attached, then opens a pre-filled GitHub issue (you need a free GitHub account; the complete report is copied to your clipboard to paste over the trimmed part, or use Save as file...). You can tick Attach a screenshot (needs pip install pillow): it photographs mcIRC's own windows, blacks out chat text, names and the button bar by default, and a help window then walks you through pasting the log and the picture into GitHub. The log is also in the diagnostics folder (Help > Open troubleshooting logs folder); the last 5 runs are kept. It records versions, USB serial ports, connection steps, which meshcli commands worked or failed, your node's firmware and radio settings, and errors. It never contains message text (public or private), passwords, your position, whole public keys or full Bluetooth/IP addresses.

Still stuck? Open a Bug report with your version (Help > About) and the relevant Status window lines - remove anything private first.

The Mesh bot answers path with "which repeaters isn't known" The repeaters are read from the radio packets mcIRC hears while it listens between polls (USB, Wi-Fi and Bluetooth). Check Options > Node memory > Listen between polls is ticked, and update mcIRC (older versions couldn't listen over Bluetooth). Now and then a packet is missed - for example while mcIRC reconnects - so ask again.

Bluetooth: Windows says "That PIN didn't work" A node with a screen and no fixed PIN makes up a new random PIN at every start and shows it on the screen - 123456 only works on nodes without a screen or with that PIN set. Wake the screen (press the node's button) and type the number shown, or set a fixed PIN in the node's settings, restart it, remove the node in Windows' Bluetooth settings and pair again. See Connecting Your Radio.

Area alerts is on, but nothing goes out Tick Broadcast to the mesh (off by default): without it alerts only show in the Area alerts window. The first check after starting or adding areas only shows what is already in force - only new alerts are sent. If Status says the node has no free channel slot, make room in MeshCore tools > Channels (each kind's channel is added to the node for you). Traffic, transit and weather is now part of Area alerts: its settings moved there when you updated.

Status says "Your settings file couldn't be read" / "couldn't be opened" mcIRC started with default settings, and your own settings are safe (mcIRC 2026.10.23-4). Couldn't be read: the file was damaged (for example by a power cut while saving with an older version); it was kept as gui_settings.json.broken-<date-time> next to mcIRC.py. Settings you change now are saved in a new file. Couldn't be opened: something held the file at startup (cloud sync such as OneDrive, or antivirus); mcIRC won't save over it this session - close what holds it and restart mcIRC, and everything is back. Since this version settings are saved whole or not at all, so an interrupted save can't damage the file.

The map shows "Access blocked" / 403 tiles instead of streets OpenStreetMap refused the map library's generic name. Update mcIRC (2026.10.23 or later: Help > Check for updates) and restart it - tiles are then fetched under mcIRC's own name and kept on your PC.