Troubleshooting

Service Won't Start

Check logs immediately after start attempt

sudo systemctl start mesh-dash
sleep 2
journalctl -u mesh-dash -n 50 --no-pager

Virtual environment missing

# The run script checks for this explicitly
ls /opt/meshdash/mesh-dash_venv/bin/python
# If missing, recreate:
cd /opt/meshdash
python3 -m venv mesh-dash_venv
source mesh-dash_venv/bin/activate
pip install -r requirements.txt

Import error — missing module

source /opt/meshdash/mesh-dash_venv/bin/activate
python3 -c "import meshtastic; import fastapi; import uvicorn"
# Install any missing packages:
pip install -r requirements.txt

Radio Connection Issues

Permission denied on serial port

sudo usermod -aG dialout $USER
# Log out and log back in (or newgrp dialout for immediate effect)
groups | grep dialout

Port is busy

# Find what's using the port
fuser /dev/ttyACM0

# Kill it if safe to do so
fuser -k /dev/ttyACM0

Device not found after plug-in

# Check kernel messages
dmesg | tail -30

# List serial devices
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

# Verify it's a data cable (not charge-only)
# Try a different USB port and cable

Dashboard shows "Reconnecting" forever

• Check that no other application (Meshtastic Python CLI, mobile app via USB) is holding the serial port
• Increase SCHEDULER_CONNECT_TIMEOUT and SCHEDULER_RW_TIMEOUT in the config
• Check /api/system/connection_history to see how often and how quickly it's reconnecting

Dashboard / Browser Issues

Can't reach http://device-ip:8000

# Is the service running?
sudo systemctl status mesh-dash

# Is it bound to the right interface?
ss -tlnp | grep 8000

# Is a firewall blocking it?
sudo ufw status
sudo ufw allow 8000/tcp

Blank page or old content loading

# Hard refresh: Ctrl+Shift+R  (bypass browser cache)
# The API always sets Cache-Control: no-store on HTML pages

Authentication Problems

Locked out / forgot password

MeshDash does not have a built-in password reset flow. To reset:

source /opt/meshdash/mesh-dash_venv/bin/activate
cd /opt/meshdash

# Open the SQLite database
sqlite3 meshtastic_data.db

# Delete the user account (this re-enables the setup flow on next restart)
DELETE FROM users WHERE username = '[email protected]';
.quit

sudo systemctl restart mesh-dash
# Visit /setup to create a new admin account

Setup page shows "already initialized" but I can't log in

This means users exist but the setup wizard is blocking. Use the sqlite reset above.

All sessions invalidated after restart

This happens when AUTH_SECRET_KEY changes (e.g. after a fresh install over an existing one). Log in again. Set a stable key in .mesh-dash_config to prevent this.

Database Issues

SQLite "database is locked"

# Stop the service first
sudo systemctl stop mesh-dash

# Check integrity
sqlite3 /opt/meshdash/meshtastic_data.db "PRAGMA integrity_check;"

# Rebuild WAL file if stuck
sqlite3 /opt/meshdash/meshtastic_data.db "PRAGMA wal_checkpoint(TRUNCATE);"

sudo systemctl start mesh-dash

Disk space full (database growing)

# Check sizes
du -sh /opt/meshdash/*.db

# Reduce retention (restart required)
# Edit .mesh-dash_config: HISTORY_DAYS=7

# Manual vacuum
sudo systemctl stop mesh-dash
sqlite3 /opt/meshdash/meshtastic_data.db "VACUUM;"
sudo systemctl start mesh-dash

Update Failures

Update downloaded but not applied

# Check if staging files exist
ls /opt/meshdash/.update_ready /opt/meshdash/update.zip

# If they exist and the service is running, the update will apply on next restart:
sudo systemctl restart mesh-dash

# To cancel a staged update:
rm /opt/meshdash/.update_ready /opt/meshdash/update.zip

The mesh_dash_tools.sh Admin menu (option 2) also provides a "Clear Stuck Update Flags" option.

After an update, something is broken

# Restore the previous database backup
bash mesh_dash_tools.sh
# → Option 2 (Database Management) → Restore Most Recent Backup

# Or manually:
cp /opt/meshdash/backup/sql/TIMESTAMP_meshtastic_data.db \
   /opt/meshdash/meshtastic_data.db

Plugin Problems

Plugin stuck in "crashed" state

# Check the plugin's log buffer via the API
curl -b "access_token=Bearer ..." \
     http://device-ip:8000/api/system/plugins/my_plugin/logs

Common causes: syntax error in main.py, missing import, or exception in init_plugin(). Check logs, fix the code, and restart the service.

Plugin "hung" — routes returning 503

A plugin with "watchdog": true in its manifest has not updated context["plugin_watchdog"][pid] = time.time() within 120 seconds. The background task has likely deadlocked or crashed silently. Check the plugin logs and fix the background loop.

Collecting Debug Info for Support

# System info
uname -a
python3 --version

# Service status
sudo systemctl status mesh-dash

# Last 100 log lines
journalctl -u mesh-dash -n 100 --no-pager

# Config (REDACT sensitive values before sharing)
grep -v "SECRET\|KEY\|PASSWORD\|MAC" /opt/meshdash/.mesh-dash_config

# Database sizes
du -sh /opt/meshdash/*.db

# Disk space
df -h /opt/meshdash

Web Serial Issues

WEB SERIAL button not appearing

The button only appears when MESHTASTIC_CONNECTION_TYPE=WEBSERIAL is set in .mesh-dash_config and the service has been restarted. Check Settings → Primary Radio Connection shows WEB SERIAL selected.

"USB N/A" shown in topbar

Your browser does not support the Web Serial API. Web Serial requires Chrome 89+ or Edge 89+ on HTTPS or localhost. It does not work in Firefox, Safari, or over plain HTTP.

Browser port picker opens but radio not listed

The vendor ID filter only shows known Meshtastic chipsets. Some boards use different chips. Try dismissing the filtered picker — some Chrome versions allow viewing all ports. Check Device Manager (Windows) or lsusb (Linux) to find the vendor ID and report it.

Port opens but no packets arrive

1. Try different baud rates: 115200 is standard but some boards use 921600
2. Check that the radio firmware is not in flash/DFU mode (it won't send packets)
3. Verify DTR/RTS release is working — some ESP32 boards reset when DTR is asserted
4. Check browser console for WebSerial read loop errors

Frontend / Browser Issues

View shows blank after navigation

# Check browser console (F12) for errors
# Most common: JS module failed to load, or view init threw an exception
# Try Ctrl+Shift+R to hard-refresh (clear cache)

SSE stream never connects

# Check that /sse endpoint is reachable
curl -N http://device-ip:8000/sse

# If it hangs, the service is running but SSE is broken
# Check journalctl -u mesh-dash for SSE errors

# Common cause: reverse proxy (nginx/Apache) buffers SSE
# Add to your proxy config:
# X-Accel-Buffering: no
# proxy_buffering off;

Dashboard stops updating after ~90 seconds

The SSE watchdog fires after 90 seconds of silence and forces a reconnect. If this keeps happening, the SSE stream is being dropped by a network device (load balancer, proxy, corporate firewall). Either add SSE-compatible proxy headers or access MeshDash directly without a proxy.

Node list shows 0 nodes but radio says it sees nodes

1. Wait for the background sync to complete (SSE sync_status event with is_syncing: false)
2. The sync can take 10–30 seconds on first connection
3. If nodes never appear, try --nodes in the C2 Terminal to verify the radio reports them

Map shows no nodes even though nodes exist

Only nodes with valid GPS coordinates appear on the map. Check the Overview — if nodes show no latitude/longitude, their GPS is disabled, they haven't got a fix yet, or position broadcasting is disabled on the node.