Skip to main content
Version: v25.07.31

Failover Troubleshooting

This document outlines troubleshooting steps specific to Multi-WAN Failover mode, where one WAN interface should take over only when the primary connection fails. In a Failover, traffic flows primarily through a preferred WAN link and only switches to a backup link when the primary fails. This guide helps ensure your failover settings are correctly configured and functioning.

Summary Table for Common Issues and Fixes​

IssuePossible CauseRecommended Action
All traffic on one WANIncorrect weight/metric or disabled interfaceCheck and correct weights and enable all intended interfaces
Failover not happening           mwan3 service stopped or misconfiguredStart/restart mwan3 service; verify config files
Ping fails on specific WANWAN connection problem or tracking IP unreachableCheck physical connection and ISP status; verify track IPs
Traceroute shows single pathRouting or policy misconfigurationCheck mwan3 policies and rules; ensure failover is enabled 
Logs show errors related to mwan3Config errors or interface issuesReview and fix errors from logs

Troubleshooting Steps​

Cloud Configuration Verification​

Verify Current Load Balancing Configuration:​

Log into the CE device and gain root access:

sudo su -

Run the following command to display the last applied multi-WAN configuration, ensuring that the mode is set to Failover.

cat /tmp/last_config_response.json | jq .multiWanV2

The given one is just an example output; when this command is run, it will show something like this.

Example Response​

{
  "enable": true,
  "mode": "FAIL_OVER",
  "notificationEmails": [
    "apex_connect.ltd1@gmail.com"
  ],
  "wanInterfaces": null,
  "wanInterfacesConfig": {
    "pppoe0": {
      "interfaceName": "pppoe0",
      "targetIps": [
        "8.8.8.8",
        "4.2.2.2"
      ],
      "failureInterval": 5,
      "recoveryInterval": 5,
      "pingInterval": 5,
      "pingTimeout": 2,
      "multiWANMetric": 3,
      "multiWANWeight": 2,
      "enable": false
    },
    "eth0": {
      "interfaceName": "eth0",
      "targetIps": [
        "8.8.8.8",
        "4.2.2.2"
      ],
      "failureInterval": 5,
      "recoveryInterval": 5,
      "pingInterval": 5,
      "pingTimeout": 2,
      "multiWANMetric": 1,
      "multiWANWeight": 2,
      "enable": true
    },
    "wlm0": {
      "interfaceName": "wlm0",
      "targetIps": [
        "8.8.8.8",
        "4.2.2.2"
      ],
      "failureInterval": 5,
      "recoveryInterval": 5,
      "pingInterval": 5,
      "pingTimeout": 2,
      "multiWANMetric": 2,
      "multiWANWeight": 2,
      "enable": false
    }
  }
}

Please carefully check that the mode is set to failover. In a failover setup, the multiwan Metric values assigned to each WAN interface define their priority: a lower metric typically indicates a higher priority (primary WAN), while higher metrics indicate secondary or tertiary WANs. Ensure these metrics are correctly configured to establish the desired failover order. Also, confirm that all intended WAN interfaces have enable: true.

Q:1 What is Failover mode?

Failover mode is a Multi-WAN configuration where: Traffic flows through the primary WAN interface (lowest metric).If the primary WAN fails (due to link down, ping timeout, or unreachable target IP), traffic is automatically switched to a backup WAN interface. Once the primary WAN recovers, traffic is routed back to it. Failover mode ensures network redundancy and uninterrupted connectivity by automatically switching between WAN links when failures occur.

Q:2 How to check Failover multi-WAN JSON configuration?

To check the Failover multi-WAN configuration: Log into the CE device with root access: sudo su -, Run the command: cat /tmp/last_config_response.json | jq .multiWanV2. Verify the following in the output: Mode is set to "FAIL_OVER". Enable is set to true. Metrics – Ensure the interface with the lowest metric (e.g., 1) is the primary WAN. Weights – Confirm weights are correctly assigned for backup interfaces. Target IPs – Check that valid tracking IPs (e.g., 8.8.8.8, 4.2.2.2) are configured.