Troubleshooting Guide

September 2, 2026 · View on GitHub

Common issues and solutions for mc-webui.

Table of Contents

Common Issues

Container won't start

Check logs:

docker compose logs -f mc-webui

Common causes:

  • Serial port not found → Verify MC_SERIAL_PORT in .env
  • Permission denied → Add user to dialout group
  • Port 5000 already in use → Change FLASK_PORT in .env

Cannot access web interface

Check if port is open:

sudo netstat -tulpn | grep 5000

Check firewall:

# Allow port 5000 (if using UFW)
sudo ufw allow 5000/tcp

Check container is running:

docker compose ps

No messages appearing

Check device connection:

# Check container logs for device communication
docker compose logs -f mc-webui

Check database:

# Verify the database file exists
ls -la data/meshcore/*.db

Check System Log in the web UI (Menu → System Log) for real-time device event information.

Device not found

# Check if device is connected
ls -l /dev/serial/by-id/

# Verify device permissions
sudo chmod 666 /dev/serial/by-id/usb-Espressif*

USB device errors

Check device connection:

ls -l /dev/serial/by-id/

Restart container:

docker compose restart mc-webui

Check device permissions:

ls -l /dev/serial/by-id/usb-Espressif*

Should show crw-rw---- with group dialout.

Device not responding

Symptoms:

  • Container logs show repeated no_event_received errors and restarts: 
    ERROR:meshcore:Error while querying device: Event(type=<EventType.ERROR: 'command_error'>, payload={'reason': 'no_event_received'})
  • Device name not detected (auto-detection fails)
  • All commands timeout in the Console

What this means:

The serial connection to the USB adapter (e.g. CP2102) is working, but the MeshCore device firmware is not responding to protocol commands. The device boots (serial port connects), but the application code is not running properly.

What does NOT help:

  • Restarting Docker containers
  • Restarting the host machine
  • USB reset or USB power cycle (only resets the USB-to-UART adapter, not the MeshCore radio module)

Fix: Re-flash the firmware

The MeshCore device firmware is likely corrupted. Re-flash the latest firmware using the MeshCore Flasher:

  1. Download the latest firmware from MeshCore releases
  2. Flash using MeshCore Flasher or esptool
  3. Restart mc-webui: docker compose up -d

This can happen after a power failure during OTA update, flash memory corruption, or other hardware anomalies.

BLE Connection Issues

If using Bluetooth Low Energy (BLE) transport, see the dedicated Bluetooth Pairing Guide for setup and troubleshooting, including:

  • Host preparation (BlueZ configuration, ControllerMode = le)
  • Pairing with fixed PIN
  • Trusting the device for automatic reconnection
  • Diagnosing connection loops and stale BlueZ connections

Map is empty, or a route is drawn across the whole world

If the contacts map comes up blank once Cache is switched on, while the same map with Cache off looks fine — or if the Path Analyzer draws a route as one long line stretching across the globe — the cause is a contact whose advert was corrupted in flight and now claims an impossible position, such as a latitude of 1642 degrees.

The map fits itself around everything it is given, so a single such entry zooms it out until that point is on screen and pushes every real contact outside the window. Nothing is wrong with the contacts you cannot see.

Fixed in 2.13.0: impossible positions are discarded on the way into the cache and again on the way out to the browser, so updating is enough — the cache heals itself and nothing needs to be deleted. The affected contacts stay in your contact list; they simply no longer appear on any map.

If you want to find them anyway, the System Log (Menu → System Log) records each one as it arrives:

Dropping out-of-range advert coordinates for <name> (<pubkey>...): lat=... lon=...
Corrupted advert type for <name> (<pubkey>...): type=...

They can be removed under Contacts → Manage like any other cached contact, but there is no need to.

Contact Management Issues

Check logs:

# mc-webui container logs
docker compose logs -f mc-webui

You can also check the System Log in the web UI (Menu → System Log) for real-time information about contact events and settings changes.

Update asks for a GitHub username

mcupdate (or a plain git pull) stops and waits at:

Username for 'https://github.com':

even though mc-webui is a public repository that needs no credentials.

This is not an authentication problem, and nothing is wrong with your install. GitHub's HTTP/2 front end rejects the anonymous git-upload-pack request sent by older git builds — notably the git 2.39 / libcurl 7.88 combination that ships with Debian 12 — and git reports that 401 as a credential prompt. Press Ctrl+C; typing a username or a token will not help.

Fix — tell git to speak HTTP/1.1 to GitHub:

git config --global http.version HTTP/1.1

If it still asks for a username after that, you are updating with sudo. --global writes to the config of the user who runs it, and root has its own — so set it for root as well:

sudo git config --global http.version HTTP/1.1

Setting it on the repository itself works too, and does not care who runs the update: cd ~/mc-webui && git config http.version HTTP/1.1.

Then run mcupdate again. From 2.14.0 on, update.sh sets this for its own pull, so the manual command is only needed to update to that version — or for git pull commands you run yourself.

Recording a Diagnostic Capture

Some problems cannot be diagnosed from a screenshot or a log excerpt — most often "my message got no repeater badge". A capture records what the app actually received from the radio, so whoever is helping you can tell the difference between nobody repeated it and the repeat never reached the app.

Recording one

  1. Open Settings → Diagnostics.
  2. Pick how long to record (5–60 minutes) and optionally add a note describing what you are trying to catch.
  3. Press Start recording. A red Recording marker appears in the status bar under the chat.
  4. Reproduce the problem — if it is about a message that gets no badge, send that message now and wait a minute or two for repeats to come back.
  5. Press Stop and save. The capture appears in the list below.

Recording stops on its own after the chosen time, or once the file reaches 25 MB. At most 10 captures are kept; the oldest is dropped when a new one is saved.

What is in it, and who should get it

A capture contains the text of every message received while it was running, plus contact names and public keys. It does not contain channel encryption keys or any password you have stored. Treat it as you would a chat export: only send it to someone you trust.

Each saved capture can be:

  • Downloaded — send it on however you like.
  • Sent directly — only if the maintainer gave you an upload token. Paste it under Sending, then use the upload button on the capture; you get back a link to pass on. With no token nothing is ever sent anywhere.

Reading one (for maintainers)

python scripts/diag_report.py mc-webui-diag-20260808T124505Z.zip

The report opens with the measurement that matters: the device's own packets.recv counter delta over the capture window against the number of RX-log frames the app actually logged in that same window.

  • Numbers close together — the companion link is fine. A missing badge means nothing in earshot repeated that packet, or the repeat collided with another transmission.
  • Device counted far more — frames are being dropped between the device and the app. The firmware buffers four frames and discards the rest silently. This is most likely on BLE (one frame per 60 ms), possible on WiFi/TCP under load, and effectively absent on USB. Suggest a different transport before looking for an app-side cause.

The rest of the report covers frame arrival gaps (bursts are what overrun that buffer), a per-sent-message verdict, and any warnings from the log. Add --frames for a full frame listing, --verbose for payload details.

Docker Commands

View logs

docker compose logs -f mc-webui

Restart

docker compose restart mc-webui

Start / Stop

# Start the application
docker compose up -d

# Stop the application
docker compose down

# Rebuild after code changes
docker compose up -d --build

Check status

docker compose ps

Access container shell

docker compose exec mc-webui sh

Backup and Restore

All important data is in the data/ directory.

You can create and download database backups directly from the web UI:

  1. Click the menu icon (☰) → "Backup"
  2. Click "Create Backup" to create a timestamped backup
  3. Click "Download" to save a backup to your local machine

Manual backup (CLI)

cd ~/mc-webui
tar -czf ../mc-webui-backup-$(date +%Y%m%d).tar.gz data/

# Verify backup
ls -lh ../mc-webui-backup-*.tar.gz
  • Weekly backups of data/ directory
  • Before major updates
  • After significant configuration changes

Restore from backup

# Stop application
cd ~/mc-webui
docker compose down

# Restore data
tar -xzf ../mc-webui-backup-YYYYMMDD.tar.gz

# Restart
docker compose up -d

Next Steps

After successful installation:

  1. Join channels - Create or join encrypted channels with other users
  2. Configure contacts - Enable manual approval if desired
  3. Test Direct Messages - Send DM to other COM contacts
  4. Set up backups - Schedule regular backups of data/ directory
  5. Read full documentation - See User Guide for all features

Getting Help

Documentation:

Issues: