EVPN VXLAN troubleshooting is easier when you stop treating the fabric as one mysterious overlay and start checking it in layers: underlay reachability, BGP EVPN control plane, VXLAN data plane, and tenant routing. Most outages in a data center fabric are not caused by an exotic protocol bug. They are usually caused by a missing route, a mismatched VNI, an anycast gateway inconsistency, an MTU problem, or a route target that does not match the intended tenant.
This guide gives a practical workflow for network engineers operating EVPN/VXLAN fabrics. The commands differ between Cisco, Juniper, Arista, Nokia, FRRouting, and SONiC, but the logic is portable. If you can prove each layer independently, you can isolate most problems quickly without guessing.
1. Start with a Simple Mental Model
In a typical EVPN/VXLAN design, leaf switches act as VTEPs. The underlay provides IP reachability between VTEP loopbacks, usually with OSPF, IS-IS, or eBGP. The overlay uses BGP EVPN to advertise MAC addresses, IP addresses, prefixes, Ethernet segments, and VTEP next hops. VXLAN encapsulates tenant traffic between VTEPs using a VNI.
When something breaks, map the symptom to the layer:
- No VTEP reachability: suspect the underlay, loopback advertisement, ECMP, MTU, or ACL/filtering.
- MAC or ARP entries missing: suspect BGP EVPN route exchange, route targets, VLAN-to-VNI mapping, or host attachment.
- Same subnet works locally but not remotely: suspect Layer 2 VNI, type-2 routes, VXLAN UDP reachability, or MTU.
- Inter-subnet routing fails: suspect Layer 3 VNI, anycast gateway, VRF route targets, or symmetric IRB configuration.
2. Verify the Underlay Before Looking at EVPN
EVPN cannot repair a broken underlay. Before checking MAC routes or VNIs, prove that every VTEP loopback can reach every other VTEP loopback with the expected source address. This matters because VXLAN packets are sourced from the local VTEP IP and destined to the remote VTEP IP.
# Generic checks to adapt to your NOS
ping <remote-vtep-loopback> source <local-vtep-loopback>
traceroute <remote-vtep-loopback> source <local-vtep-loopback>
show ip route <remote-vtep-loopback>
show isis route / show ospf route / show bgp ipv4 unicast
Look for asymmetric reachability, unexpected next hops, missing loopbacks, or a single failed spine path causing ECMP imbalance. If your fabric uses jumbo frames, test with a payload that represents VXLAN overhead. A classic Ethernet frame plus VXLAN, UDP, IP, and outer Ethernet headers needs additional headroom. If the underlay MTU is too small, small pings may pass while real tenant traffic is dropped or fragmented.
3. Check BGP EVPN Adjacencies and Address Families
Once the underlay is stable, confirm that BGP EVPN sessions are established and that the EVPN address family is active. In many fabrics, IPv4 unicast BGP can be up while EVPN is not activated for a neighbor. That creates a deceptive state: the underlay looks healthy, but no MAC/IP routes are exchanged.
show bgp l2vpn evpn summary
show bgp evpn summary
show bgp neighbors <peer> advertised-routes
show bgp neighbors <peer> received-routes
Focus on three details: session state, route count, and next-hop handling. EVPN routes should carry a VTEP next hop that other leaf switches can resolve through the underlay. If route reflectors are used, make sure they preserve the next hop as required by the design and that clients are exchanging the correct EVPN address family.
4. Understand EVPN Route Types During Troubleshooting
You do not need to memorize every EVPN route type to troubleshoot effectively, but you should recognize the routes tied to common symptoms:
- Type 2: MAC/IP advertisement. Used for endpoint learning and ARP/ND suppression.
- Type 3: Inclusive multicast Ethernet tag route. Used for BUM traffic discovery in many designs.
- Type 5: IP prefix route. Used for advertising routed prefixes between VRFs in EVPN fabrics.
If a remote host is unreachable in the same subnet, search for its MAC and IP in the EVPN table. If the route is absent everywhere, the local leaf may not be learning the endpoint or advertising the VNI. If the route is present on the advertising leaf but absent on the receiving leaf, suspect route targets, import policy, route reflection, or EVPN address-family configuration.
5. Validate VLAN, VNI, and Route Target Mapping
One of the most common EVPN/VXLAN failures is a simple mapping error. A VLAN may be mapped to VNI 10100 on one leaf and VNI 10010 on another. A VRF may import the wrong route target. A tenant may have the correct Layer 2 VNI but the wrong Layer 3 VNI. These issues often look like random host reachability problems because local switching continues to work.
Build a small source-of-truth table for each tenant:
- Tenant or VRF name
- VLAN ID and subnet
- Layer 2 VNI
- Layer 3 VNI
- Route distinguisher and route targets
- Anycast gateway IP and MAC
Then compare the live device configuration against that table. This is where automation helps: even a short Python script or Ansible playbook that audits VLAN-to-VNI consistency can catch outages before users do.
6. Troubleshoot Anycast Gateway and IRB Problems
In modern EVPN/VXLAN fabrics, hosts often use an anycast gateway configured identically on every leaf. The gateway IP and virtual MAC must be consistent. If one leaf uses a different virtual MAC, endpoints may ARP successfully but traffic can fail after moving between racks. If one leaf misses the SVI or IRB interface, local hosts may have no default gateway even though remote EVPN routes are present.
For symmetric IRB designs, verify both the Layer 2 VNI and the Layer 3 VNI. The ingress leaf routes traffic from the source VLAN into the tenant VRF, sends it across the fabric with the L3 VNI, and the egress leaf routes it toward the destination VLAN. A missing L3 VNI or VRF route target can break inter-subnet traffic while same-subnet bridging still works.
7. Data Plane Checks: VXLAN UDP and MTU
BGP EVPN can look perfect while encapsulated packets are being dropped. VXLAN normally uses UDP port 4789. Check whether firewalls, underlay ACLs, CoPP policies, or fabric security filters permit VTEP-to-VTEP VXLAN traffic. In a tightly controlled data center, an underlay filter that permits BGP and ICMP but blocks UDP 4789 will produce exactly this failure pattern: control plane up, data plane down.
MTU is the second frequent data plane issue. Use a large ping with the do-not-fragment bit where supported, sourced from the VTEP loopback or routed interface used for encapsulation. Also inspect interface counters for drops, giants, MTU errors, and discards. A single undersized link in an ECMP path can create intermittent application issues that are hard to reproduce.
8. A Practical Troubleshooting Sequence
- Identify one failing source, destination, VLAN, VRF, and leaf pair.
- Verify local host learning on the ingress leaf: MAC table, ARP/ND table, and interface state.
- Confirm the local VLAN-to-VNI and VRF-to-L3-VNI mapping.
- Check whether the destination MAC/IP or prefix exists in the EVPN table.
- Verify that the EVPN next hop is the expected remote VTEP and is reachable in the underlay.
- Test VXLAN data plane reachability and MTU between VTEPs.
- Review route targets and import/export policies for the tenant VRF.
- Check counters on access, fabric-facing, and loopback-related paths.
This sequence prevents a common mistake: jumping straight into BGP policy while the real issue is a disconnected server port, or chasing interface counters while the remote MAC route was never imported.
Lab Practice Idea
Build a three-leaf, two-spine EVPN/VXLAN lab in containerlab, EVE-NG, CML, or your preferred virtual NOS environment. Create two tenants, two Layer 2 VNIs, and one Layer 3 VNI. After the baseline works, intentionally break one thing at a time: change a VNI on one leaf, remove a route target import, lower the MTU on one underlay link, and disable EVPN activation for one neighbor. For each fault, write down the symptom, the command that exposed it, and the fix.
Summary
Good EVPN VXLAN troubleshooting is a layered process. Prove the underlay first, then validate BGP EVPN route exchange, then inspect VLAN/VNI/VRF mappings, and finally test the VXLAN data plane. Most incidents become much smaller when you reduce them to one failing endpoint pair and one tenant. The goal is not to run every command on every switch; the goal is to prove where the packet stops being forwarded correctly.


