enFlowMeshTroubleshooting

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 symptomMeaning and action
RunningThe mesh engine is running; continue checking the peer and the actual service
NeedsLoginConnecting hasn’t completed; check the mesh address and that the key is valid
StoppedThe connection is stopped; a retained peer list does not mean those peers are still communicating
Can’t connect to the local socketCheck whether the flowmeshd service is running
Health has contentRead 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-pager

On 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.2
  • no 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 reply or 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:

  1. Whether the service on the target device is running and the port is correct.
  2. 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.
  3. Whether the host firewall and the mesh network access rules allow the protocol and port.
  4. Whether --shields-up is 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

SymptomNext step
Can reach the gateway but not its LAN devicesCheck forwarding, route approval, accepting routes and return routing; see Subnet routes
IP works, device name failsCheck the system’s actual DNS configuration; see DNS
No internet after selecting an exitCheck that the exit is online, the route is approved and it has internet connectivity; deselect it if necessary. See Exit nodes
Serve returns 404Access it using the serving node’s name and the correct path
Serve returns 502Check the backend service actually running on the serving node

6. Collect diagnostic information

flowmesh bugreport

The 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.