Troubleshooting

Troubleshooting

Commands are for the systemd package. With Docker, run them in the package's docker/ folder and use the Docker equivalents noted below.

Collect the basics

systemctl status vonode vonode-gateway
journalctl -u vonode -n 200 --no-pager
lsusb | grep -i -E 'quectel|2c7c|qualcomm|05c6'
ls /dev/ttyUSB* /dev/cdc-wdm*

Docker: sudo docker compose ps and sudo docker compose logs vonode.

"ModemManager is running"

ModemManager takes the serial ports before Vonode does. Disable it and restart the node:

sudo systemctl disable --now ModemManager
sudo systemctl restart vonode

Docker: run sudo ./setup.sh again instead of the restart.

No module detected

• lsusb shows nothing from Quectel (2c7c): try another cable and port, use a powered USB hub, and check the kernel log for USB power errors ("over-current", "device not accepting address"):

  sudo dmesg | tail -n 30

• lsusb lists the module but /dev/ttyUSB* is missing: load the drivers, then unplug and replug the module:

  sudo modprobe -a option qmi_wwan

• Some adapters ship with the module in a mode without USB serial ports; follow the adapter vendor's instructions to enable them.

• A DJI Cellular module reports a DJI USB ID (2ca3:4006) until its USB identity is switched once; see the hardware page.

• Two or more modules on unpowered motherboard ports often cause random resets and "modem disappeared" problems. A module draws up to 2 A at transmit peaks; use a powered hub.

Ports changed after a module reset

A module that resets re-enumerates and may get other ttyUSB numbers. The systemd package and the default Docker /dev binding pick them up by themselves. If you set up Docker with --devices, run sudo ./setup.sh again.

The app cannot connect

From a device outside your network, test the port:

nc -vz node.example.com 2222

No answer means the router forward or firewall is wrong, or your internet provider uses carrier-grade NAT (no public IPv4). In that case, run a VPN (WireGuard, Tailscale) between the phone and the host and pair with the host's VPN address. See Pairing the app.

Pairing code expired or already used

Codes last five minutes and work once. Run the pair command again.

Wi-Fi calling will not register

• The carrier must enable Wi-Fi calling on the plan, exactly as for a phone.
• The module must have registered on the cellular network at least once with that SIM.
• The host needs working IPv6 or IPv4 to the carrier's ePDG.
• The host needs the full iproute2 package and /dev/net/tun.

The app's diagnostics page shows the current phase. The support bundle it can export is what to send to support@vonode.cc.

Wrong time in messages

The node uses the host's time zone. Set it with timedatectl. With Docker, pass --tz Europe/London (an IANA zone name) to setup.sh.

Docker only

• Containers not healthy: sudo docker compose logs vonode shows why. The core is healthy once its internal socket exists; vonode-gateway once it can reach that socket and listen on 2222. A port conflict on 2222 (ss -ltn | grep 2222) is the usual cause; choose another port with --port.
• 127.0.0.1:7575 is already in use: another program uses the node's local pairing-page port. Run sudo ./setup.sh --admin-port 17575 (any free port).

Lost administrator password

sudo systemctl stop vonode
sudo /opt/vonode/vonode reset-password -c /opt/vonode/config/config.yaml
sudo systemctl start vonode

All phones are signed out and pair again.

Still stuck?

Email support@vonode.cc with the node version, your module model, what you tried and the support bundle from the app.