Troubleshoot connections
Start with “is the client running”, then check the node path, service ports and DNS. Record the current state first, so you don’t end up unable to tell the cause after changing several options in a row.
The commands below apply to Linux FlowMesh; on OpenWrt, LuCI / UCI settings take precedence.
1. Check local status
flowmesh status
flowmesh status --json| Status or symptom | Meaning and action |
|---|---|
Running | The mesh engine is running; continue checking the peer and the actual service |
NeedsLogin | Connecting hasn’t completed; check the mesh address and that the key is valid |
Stopped | The connection is stopped; a retained peer list does not mean those peers are still communicating |
| Can’t connect to the local socket | Check whether the flowmeshd service is running |
Health has content | Read the specific message, for example DNS not taken over or exit node offline |
On Linux systemd systems, check the service and logs:
sudo systemctl status flowmeshd
sudo journalctl -u flowmeshd -n 100 --no-pagerOn OpenWrt, check the LuCI status and logs first; you can also run logread -e flowmesh.
2. Connecting fails
Confirm that the mesh address exactly matches 设置 → 网络配置 → 组网控制器 (Settings → Network configuration → Mesh controller) for the mesh network in the console, including the protocol, domain or IP, and port. The first connection must specify --login-server.
Check that the key is valid, that a one-time key hasn’t already been used, and that the mesh network can still add devices. If the network times out, first check whether this device can reach the control server; don’t troubleshoot network problems by repeatedly generating keys.
If up reports missing non-default parameters, keep the existing settings as prompted; use set to change only one option. --reset resets unspecified settings and is not a general-purpose fix.
3. Is the node reachable
Replace the example with the peer’s actual address:
flowmesh ping --until-direct=false -c 3 100.64.0.2no matching peer: check whether the peer is visible in the current mesh network, whether the address is correct, and the access policy.peer's node key has expired: update the device’s connection identity as your admin requires.no replyor a timeout: check the peer’s online status, the networks on both ends, and relay connectivity.- A relayed
pong: the path is reachable; the default probe reporting that no direct connection was established doesn’t mean the relay is unusable.
To check network conditions, run flowmesh netcheck, but it requires the client to have received the relay list.
4. The node responds, but the service won’t open
Check in order:
- Whether the service on the target device is running and the port is correct.
- Whether the service only listens on
127.0.0.1. Such a service can be shared through Serve, or you can change its listen address as your needs require. - Whether the host firewall and the mesh network access rules allow the protocol and port.
- Whether
--shields-upis enabled on the target device.
A node path probe doesn’t verify that the application service is running and is not a substitute for testing access rules.
5. LAN devices or domain names can’t be reached
| Symptom | Next step |
|---|---|
| Can reach the gateway but not its LAN devices | Check forwarding, route approval, accepting routes and return routing; see Subnet routes |
| IP works, device name fails | Check the system’s actual DNS configuration; see DNS |
| No internet after selecting an exit | Check that the exit is online, the route is approved and it has internet connectivity; deselect it if necessary. See Exit nodes |
| Serve returns 404 | Access it using the serving node’s name and the correct path |
| Serve returns 502 | Check the backend service actually running on the serving node |
6. Collect diagnostic information
flowmesh bugreportThe command generates a diagnostic JSON file in the current directory and doesn’t upload it automatically. It includes status, settings, system network configuration and readable logs; if an item can’t be read, the failure for that item is recorded.
The tool handles specific key fields, but the report may still contain environment information such as device names, addresses, routes and logs. Review the content before sharing and remove sensitive information as needed; don’t attach auth keys or raw node identity files.
When contacting technical support, include the time of the operation, the two affected devices, the expected result, the actual error, and whether the problem started after an update or configuration change.