MeshCore App Errors and How to Fix Them
When the MeshCore app shows an error, the big line ("Failed to add contact!") says what you tried. The small line under it says why. This guide explains both and how to fix each one.
It covers the official MeshCore app on Android, iPhone, desktop and the web (app.meshcore.nz). Each cause comes from the app's messages, the firmware source or the MeshCore FAQ.
Checked October 2026 against MeshCore 1.18.0 and MeshCore app 1.50.
Find Your Error
| Error | Usual cause |
|---|---|
| Failed to add contact! (Table Full) | The radio's contact list is full |
| Failed to create channel! | Channel slots are full, or the name or key is invalid |
| Failed to fetch device info | A stale Bluetooth pairing, or an older app |
| Failed to connect! … Failed to find BLE Service | Wrong firmware, or a wrong or stale PIN pairing |
| Failed to open serial port | No permission for the USB port, or another app is using it |
| Unsupported Command - Please update your companion firmware. | The app asked for something the firmware doesn't have |
Before anything else: update the app, and make sure the radio runs companion firmware for the way you connect (Bluetooth or USB). Our firmware guide shows how to check and update.
"Failed to add contact!"
Contacts are stored on the radio, not in the app. When a new contact doesn't fit, the firmware answers with a "table full" error, and the app shows Failed to add contact! with Table Full underneath. The app can also notify you with "Contacts Full: New contacts can't be added."
Most current boards hold 350 contacts. Some older or smaller-memory builds hold between 100 and 300. On a busy mesh, auto-added contacts fill that up faster than you'd think.
Fix
- Delete old contacts. Long-press in the contacts list to select several and delete them. Settings also has an option to purge all contacts.
- Turn on Overwrite Oldest (next to the auto-add settings). When the list is full, the oldest contact that isn't a favourite is replaced. Mark the people and repeaters you want to keep as favourites first.
- Limit auto-add. The auto-add options let you choose which kinds of node get added automatically and set a maximum hop count, so distant nodes don't fill your list.
Other messages you might see when adding a contact by code or link: "You can't add yourself as a contact", "Public Key is required", "meshcore:// URL is missing type, name or public_key." (the link was cut off when copied), and "Contact Already Exists".
"Failed to create channel!"
Like contacts, channels live on the radio, in a fixed number of slots: 40 on most boards, and 8 on some older or smaller ones such as the Heltec V2, LilyGo T-LoRa V2.1 and RP2040-based boards. The detail line tells you which problem you hit.
"You have reached the channel limit."
Every slot is in use. Remove a channel you don't read anymore, then add the new one.
"Channel name must start with #" and other name errors
Hashtag channels are public: anyone who types the same name joins the same channel. The name must start with #, be at least 2 characters, use only a-z, 0-9 and hyphens, and not contain two hyphens in a row. #test-net works; #test net and #test--net don't.
"A channel with this secret key already exists."
You already have this channel, perhaps under another name. Check your channel list before adding it again.
"Not Found" or "Unsupported Command"
These come from the firmware. "Not Found" means the slot number was out of range for this radio. "Unsupported Command" means the firmware refused the request; it only supports 128-bit channel keys, and very old firmware (before 1.3.0) has no custom channels at all. Update the companion firmware.
How channels, hashtags and private keys work is covered in our MeshCore app guide.
"Failed to fetch device info"
Right after connecting, the app asks the radio for its details (name, firmware version, settings). This error usually means the radio didn't answer in time. The app's own advice appears with it: "You may need to forget this device from your Bluetooth settings and try pairing again."
Fix, in this order
- Forget and re-pair. Remove the device in your phone or computer's Bluetooth settings, reboot the radio, then connect from the app and enter the PIN. A firmware erase or factory reset wipes the radio's side of the pairing, but your phone keeps the old one, and the two no longer match.
- Update the app. Version 1.50.0 fixed some ESP32 boards timing out while fetching device info over USB on Windows.
- Update or reflash the firmware with the flasher, without erasing, so the radio runs a current companion build.
One known hardware case: RAK4631 owners have reported this error with a RAK12002 clock or other sensor modules attached, and the app connected once the modules were removed (MeshCore issue #1120). If you have add-on modules, try without them.
"Failed to connect!" and "Failed to find BLE Service"
A failed Bluetooth connection shows Failed to connect! with two hints, "The PIN you entered may be wrong" and "try rebooting your MeshCore device and forgetting it from your Bluetooth settings", followed by the technical reason. One reason users report is Failed to find BLE Service.
MeshCore companions send data over a standard Bluetooth service called the Nordic UART Service (UUID 6E400001-B5A3-F393-E0A9-E50E24DCCA9E). The error means the app reached the device but that service wasn't there, or the phone couldn't read it.
Fix
- Check the firmware. Only Companion Bluetooth firmware accepts an app connection over Bluetooth. Repeater, room server and Companion USB firmware don't. Reflash with the right role if needed.
- Forget, reboot, re-pair. Remove the device from your phone's Bluetooth settings, restart the radio and connect again from the app.
- Use the right PIN. See the next section.
- Still nothing? The app suggests turning Bluetooth off for 10 seconds and trying again. On Android, older phones need location services on for Bluetooth scanning.
Bluetooth PIN Problems
- Boards without a screen use
123456unless you've changed it. - Boards with a screen show a random six-digit PIN on the display, a new one each time they start, unless you've set your own.
- A PIN you set in the app replaces both. It must be six digits, 100000 to 999999. Otherwise the app says "Bluetooth Pin must be exactly 6 digits."
Forgot your PIN, or can't read it?
On boards with a user button (some RAK boards, the Heltec T114), hold the button within 8 seconds of boot to enter rescue mode. Connect over USB, open the Console on flasher.meshcore.io and send set pin followed by a new six-digit PIN. Otherwise, as the app itself suggests, flash the Companion USB firmware, connect over the cable, set a new Bluetooth PIN in the app's settings, then flash the Bluetooth firmware back without erasing. The PIN is kept.
"Failed to open serial port"
This one comes from the browser, in the web app or the flasher. The full text is NetworkError: Failed to execute 'open' on 'SerialPort': Failed to open serial port. The browser found the device but the operating system wouldn't let it open the port.
Fix
- On Linux, give your user access to the port (use the port your device appears as, often
/dev/ttyUSB0or/dev/ttyACM0):sudo setfacl -m u:$USER:rw /dev/ttyUSB0 - Close anything else using the port: another browser tab with the app or flasher, the MeshCore desktop app, meshcore-cli or a serial monitor. A serial port can only be open in one program at a time.
- Use Chrome or Edge. Safari doesn't support Web Serial, so the web app can't use USB there.
If the port opens but the app never finishes connecting, the radio isn't answering. Check that it runs Companion USB firmware; Bluetooth companion and repeater builds don't talk to the app over USB. The desktop apps for Windows, macOS and Linux support USB directly (since app 1.44.0), and so does the Android app (since 1.37.0).
What the Short Error Lines Mean
When the radio refuses a request, it sends back a numbered error code, and the app shows it as one of these lines under the main error.
| Code | App shows | What it means |
|---|---|---|
| 1 | Unsupported Command - Please update your companion firmware. | The firmware doesn't know this command. Usually the firmware is older than the app expects. |
| 2 | Not Found | The contact or channel slot the app asked about doesn't exist on the radio. |
| 3 | Table Full | A list on the radio (contacts, usually) has no free space. |
| 4 | Bad State | The radio can't do that right now, for example because another operation is still running. |
| 5 | File IO Error | The radio couldn't read or write its storage. |
| 6 | Illegal Arg | A value was out of range, such as a Bluetooth PIN that isn't six digits. |
Repeater logins have their own messages. "Failed to log in!" with "The password you entered may be incorrect, or this repeater may be unreachable" means a wrong password or no route to the repeater. See MeshCore repeater not working for the second case.
MeshCore App Error FAQ
Why does MeshCore say "Failed to add contact"?
Almost always because the contact list on your radio is full. The detail line under the error says "Table Full". Most boards hold 350 contacts. Delete contacts you no longer need (long-press the contacts list to select several), or turn on Overwrite Oldest so new contacts replace the oldest ones that aren't favourites.
Why does MeshCore say "Failed to create channel"?
The radio has no free channel slots, the hashtag name breaks the naming rules, or a channel with the same secret key already exists. Most boards hold 40 channels; some older or smaller boards hold 8. Delete a channel you don't use, or fix the name: it must start with #, be at least 2 characters, and use only a-z, 0-9 and single hyphens.
How do I fix "Failed to fetch device info" in MeshCore?
Forget the device in your phone or computer's Bluetooth settings, then connect again from the app and enter the PIN. That clears a stale pairing, which is common after a firmware erase or factory reset. Also update the app: version 1.50.0 fixed a timeout on some ESP32 boards over USB on Windows.
What does "Failed to find BLE Service" mean?
The app connected over Bluetooth but couldn't find the MeshCore data service on the device. Check that the device runs Companion Bluetooth firmware (repeaters and USB companions have no Bluetooth app connection), then forget it in Bluetooth settings, reboot it and pair again with the right PIN.
What is the MeshCore Bluetooth PIN?
The default is 123456 on boards without a screen. Boards with a screen show a random six-digit PIN on the display each time they start, unless you've set your own PIN in the app.
Why does the MeshCore web app or flasher say "Failed to open serial port"?
The browser could not open the USB port. On Linux the usual cause is permissions: run sudo setfacl -m u:$USER:rw /dev/ttyUSB0. On any system, close other programs using the port, such as another browser tab, the desktop app or a serial monitor, and use Chrome or Edge.
Not listed here? The MeshCore FAQ covers more, and our Discord can help.