arp / ip neigh: Usage, Options & Common CI Errors

arp shows the IP-to-MAC neighbor table for the local network segment.

arp (now superseded by ip neigh) shows which IPs the kernel has resolved to MAC addresses on the local link. An "incomplete" entry is a useful signal that a host on the same subnet is not answering at layer 2.

What it does

arp displays and manipulates the kernel's ARP (IPv4) neighbor cache - the table mapping local IP addresses to hardware MAC addresses. The modern iproute2 equivalent is ip neigh, which also covers IPv6 (NDP).

Common usage

Terminal

arp -n                         # neighbor table, numeric
arp -a                         # BSD-style listing
ip neigh show                  # iproute2 equivalent (v4 + v6)
ip neigh show dev eth0
ip neigh flush all             # clear the neighbor cache

Options

Command / flag	What it does
arp -n	Show cache without resolving names
arp -a	BSD-style "(host) at MAC" listing
ip neigh show	Modern neighbor table (IPv4 + IPv6)
ip neigh show dev <if>	Limit to one interface
ip neigh flush all	Empty the neighbor cache

Common errors in CI

"arp: command not found" - the legacy net-tools package is gone from most modern/slim images; use ip neigh instead (iproute2). An entry shown as "incomplete" (or state FAILED in ip neigh) means the kernel ARPed for that local IP and got no reply - the host is down or not on this segment. ARP is link-local only: it tells you nothing about hosts reached via a gateway, so an empty/incomplete arp entry for a remote IP is expected, not an error.