Troubleshooting

This page lists the most common problems when running DeadLetter and how to fix them.

Device setup tool does not detect my ESP32

Symptoms

  • No devices detected
  • The setup tool lists zero serial ports.

Fix

  • Make sure the ESP32 is connected with a data USB cable.
  • Install USB‑UART drivers:
    • macOS / Linux: CP210x or CH340 drivers if your board requires them.
    • Windows: Install Silicon Labs CP210x or CH340 drivers.
  • On Linux, ensure you are in the dialout group:
sudo usermod -a -G dialout $USER
# log out and back in

Permission denied opening serial port

Symptoms

  • Permission denied: /dev/ttyUSB0

Fix

sudo usermod -a -G dialout $USER

Log out and log back in.

Setup tool says “Registry gateway is NOT reachable”

Symptoms

  • Device prints: Registry gateway is NOT reachable!

Cause The ESP32 cannot reach the configured Tor gateway on the local network.

Fix

  • Ensure the Tor gateway (e.g. Raspberry Pi) is powered on.
  • Verify gateway IP + port are correct: 
    deadletter-setup -r <gateway-ip:port> -b <gateway-ip:port>
  • Check the gateway firewall allows inbound connections.

Device keeps printing Registry gateway: UNSET

Cause Gateway IP was not saved to NVS or device rebooted before storing.

Fix Run device setup again and wait until it prints Registry gateway set before disconnecting USB.

Inbox shows messages but decryption fails

Symptoms

  • Decryption failed - invalid key or corrupted data

Fix

  • Make sure the correct identity directory exists: ~/.deadletter/<handle>/
  • Ensure enc_private.key and enc_public.key belong to the same identity used by the sender.
  • Run: 
    deadletter trust
    and verify the fingerprint matches what the sender sees on their ESP32.

File downloads are saved as unreadable garbage

Cause Base64 payload corrupted or wrong key used.

Fix

  • Ensure sender and receiver verified the same trust fingerprint.
  • Retry deadletter inbox <handle>.

deadletter trust reports trust anchor changed

Symptoms

  • Warning about trust anchor mismatch.

Fix Stop immediately. Compare fingerprints with your sender through a secure channel. Only proceed if you are 100% sure the new fingerprint is legitimate.

deadletter command not found

Cause Binary is not in PATH.

Fix

sudo mv deadletter /usr/local/bin/
chmod +x /usr/local/bin/deadletter

Setup tool times out waiting for device ready

Fix

  • Unplug and reconnect the ESP32.
  • Wait until it prints Type 'help' before running setup again.

Still broken?

Enable verbose output:

deadletter-setup -v -r <gateway> -b <backend>

Attach the output when asking for support.