🚨 OpenStack Error Guide: 'binding_failed' Neutron Port Binding Failed

Overview

A Neutron port binding failure happens when Neutron cannot find an ML2 mechanism driver and L2 agent capable of wiring a port onto a compute host. Nova asks Neutron to bind the port to a host, no driver claims it, and the port’s binding:vif_type is set to binding_failed. The instance then fails to spawn.

You will see this in the Nova compute log or instance fault:

PortBindingFailed: Binding failed for port a1b2c3d4-1111-2222-3333-444455556666, please check neutron logs for more information.

And in the neutron-server log:

ERROR neutron.plugins.ml2.managers [req-...] Failed to bind port a1b2c3d4-1111-2222-3333-444455556666 on host compute-03 for vnic_type normal using segments [{'id': '...', 'network_type': 'vlan', 'physical_network': 'physnet1', 'segmentation_id': 412}]

It occurs when a port is bound to a host — almost always at instance boot, but also when attaching an interface (openstack server add port) or live-migrating. The binding is host-specific, so a port that binds fine on one compute node can fail on another.

Symptoms

• Instance goes to ERROR immediately after BUILD with fault “Binding failed for port”.
• Port shows binding_vif_type of binding_failed.
• Interface attach to a running server fails.
• neutron-server logs Failed to bind port ... using segments.

openstack server show web-01 -c fault -f value

{'code': 500, 'created': '2026-06-23T14:02:11Z', 'message': 'Build of instance 7c9e... aborted: Failed to allocate the network(s), not rescheduling.', ...}

openstack port show a1b2c3d4-1111-2222-3333-444455556666 \
  -c binding_host_id -c binding_vif_type -c binding_vnic_type -f value

compute-03
binding_failed
normal

Common Root Causes

1. The L2 agent on the target host is down

If the OVS or Linuxbridge agent on the compute host is dead or not reporting, no driver will bind the port there.

openstack network agent list --host compute-03

+--------------+--------------------+------------+-------------------+-------+-------+
| ID           | Agent Type         | Host       | Availability Zone | Alive | State |
+--------------+--------------------+------------+-------------------+-------+-------+
| 9f1a...      | Open vSwitch agent | compute-03 | None              | XXX   | UP    |
+--------------+--------------------+------------+-------------------+-------+-------+

Alive = XXX (a dead smiley) means the agent stopped heartbeating. Bindings to that host will fail until it recovers.

2. ML2 mechanism driver mismatch

The network’s segment type/driver is not enabled in mechanism_drivers, or the compute runs a different agent than the controller expects (e.g., network created for OVS but compute runs Linuxbridge).

grep -E '^(mechanism_drivers|type_drivers|tenant_network_types)' \
  /etc/neutron/plugins/ml2/ml2_conf.ini

type_drivers = flat,vlan,vxlan
tenant_network_types = vxlan
mechanism_drivers = openvswitch,l2population

If the failing segment is network_type: vlan but vlan is not in type_drivers, or the host runs linuxbridge (not listed), binding fails.

3. Wrong physnet-to-bridge mapping on the compute host

For VLAN/flat networks the agent needs a bridge mapping for the network’s physical_network. If physnet1 has no mapping on compute-03, the OVS driver refuses the port.

docker exec openvswitch_vswitchd ovs-vsctl get Open_vSwitch . \
  external_ids:ovn-bridge-mappings 2>/dev/null
grep bridge_mappings /etc/neutron/plugins/ml2/openvswitch_agent.ini

bridge_mappings = physnet2:br-ex

Here the host maps physnet2 but the port’s segment uses physnet1 — no mapping, so no bind.

4. The bridge or provider interface is missing

The mapping references a bridge that does not exist, so the agent cannot service the physnet.

docker exec openvswitch_vswitchd ovs-vsctl list-br

br-int
br-tun

br-ex (mapped to physnet1) is absent — binding fails for that physnet.

5. MTU / segment mismatch

A VXLAN/GRE overlay needs the underlay MTU to accommodate encapsulation. A network whose mtu exceeds what the agent can provide, or a segment whose segmentation_id falls outside the configured VLAN/VNI ranges, can be rejected.

openstack network show provider-412 -c mtu -c provider:segmentation_id -f value
grep -E 'network_vlan_ranges|vni_ranges' /etc/neutron/plugins/ml2/ml2_conf.ini

1500
412
network_vlan_ranges = physnet1:400:410

VLAN 412 is outside the allowed 400:410 range — the VLAN type driver will not allocate/bind it.

6. vnic_type the host cannot serve (SR-IOV / direct)

A port with binding:vnic_type of direct or macvtap requires the SR-IOV nic agent and a matching physical_device_mappings. If the host only runs the OVS agent, no driver binds a direct port.

openstack port show sriov-port-1 -c binding_vnic_type -f value
openstack network agent list --agent-type 'NIC Switch agent' --host compute-03

direct

(Empty agent list means no SR-IOV agent on the host.)

Diagnostic Workflow

Step 1: Confirm the binding state and target host

openstack port show <PORT_ID> \
  -c binding_host_id -c binding_vif_type -c binding_vnic_type -c binding_profile -f value

binding_vif_type = binding_failed confirms the failure; note the host and vnic_type.

Step 2: Verify the L2 agent on that host is alive

openstack network agent list --host <HOST>

Any agent with Alive = XXX is the prime suspect. Restart it:

# Kolla-Ansible
docker restart neutron_openvswitch_agent
# Traditional packages
sudo systemctl restart neutron-openvswitch-agent

Step 3: Read the neutron-server bind log for the exact segment

# Kolla-Ansible (controller)
docker logs neutron_server 2>&1 | grep -i "Failed to bind port" | tail -5
# Traditional
sudo journalctl -u neutron-server --no-pager | grep -i "Failed to bind port" | tail -5

This prints the segments (network_type, physical_network, segmentation_id) the binding needs.

Step 4: Check the agent on the compute host for the mapping/error

# Kolla-Ansible (on compute-03)
docker logs neutron_openvswitch_agent 2>&1 | tail -50
# Traditional
sudo journalctl -u neutron-openvswitch-agent --no-pager | tail -50
grep -E 'bridge_mappings|physical_device_mappings' \
  /etc/neutron/plugins/ml2/openvswitch_agent.ini

Compare the physical_network from Step 3 to the host’s bridge_mappings.

Step 5: Validate type ranges and bridges, then retry

docker exec openvswitch_vswitchd ovs-vsctl list-br
grep -E 'network_vlan_ranges|vni_ranges|mechanism_drivers' \
  /etc/neutron/plugins/ml2/ml2_conf.ini

After fixing the mapping/range, re-trigger the binding by resetting the port or rebuilding the server:

openstack port set --no-binding-profile <PORT_ID> 2>/dev/null
openstack server reboot --hard <SERVER>

Example Root Cause Analysis

A new instance app-07 lands on the freshly added compute-03 and immediately goes to ERROR with “Binding failed for port”.

The neutron-server log shows the segment:

ERROR neutron.plugins.ml2.managers Failed to bind port f0e1...-7788 on host compute-03 for vnic_type normal using segments [{'network_type': 'vlan', 'physical_network': 'physnet1', 'segmentation_id': 405}]

The OVS agent on compute-03 is alive, so it is not a heartbeat issue. Checking the bridge mappings on the new node:

grep bridge_mappings /etc/neutron/plugins/ml2/openvswitch_agent.ini

bridge_mappings = physnet2:br-prov2

The other compute nodes map physnet1:br-prov1, but compute-03 was provisioned with the wrong template and only has physnet2. The port’s segment needs physnet1, which this host cannot service — hence binding_failed.

Fix: add the missing mapping and create the bridge, restart the agent, then rebuild:

# add physnet1:br-prov1 to bridge_mappings, then:
docker exec openvswitch_vswitchd ovs-vsctl --may-exist add-br br-prov1
docker restart neutron_openvswitch_agent
openstack server reboot --hard app-07

The port binds to physnet1 and the instance reaches ACTIVE.

Prevention Best Practices

• Alert on dead agents: poll openstack network agent list and page when any Alive is false. Bindings silently fail the moment an agent stops heartbeating.
• Enforce identical bridge_mappings / physical_device_mappings across compute nodes via your config management (Kolla globals, Ansible templates). Most binding failures are a single mismatched host.
• Validate that every provider network’s physical_network has a corresponding mapping on all hosts in its availability zone before going live.
• Keep network_vlan_ranges and vni_ranges aligned with what the fabric actually trunks, so allocated segments are always bindable.
• Pre-flight new compute nodes with a smoke-test instance on each provider network before adding them to the scheduler pool.
• For ad-hoc triage, the free incident assistant can summarize neutron-server bind failures into the likely host/mapping cause. See more in OpenStack guides.

Quick Command Reference

# Inspect the failed binding
openstack port show <PORT_ID> -c binding_host_id -c binding_vif_type -c binding_vnic_type -f value

# Check agent health on the target host
openstack network agent list --host <HOST>

# Why did the bind fail? (controller)
docker logs neutron_server 2>&1 | grep -i "Failed to bind port" | tail -5
sudo journalctl -u neutron-server | grep -i "Failed to bind port" | tail -5

# Verify host mappings vs. the failing physnet
grep -E 'bridge_mappings|physical_device_mappings' /etc/neutron/plugins/ml2/openvswitch_agent.ini
grep -E 'mechanism_drivers|type_drivers|network_vlan_ranges|vni_ranges' /etc/neutron/plugins/ml2/ml2_conf.ini

# OVS bridges present on the host
docker exec openvswitch_vswitchd ovs-vsctl list-br

# Restart the L2 agent
docker restart neutron_openvswitch_agent
sudo systemctl restart neutron-openvswitch-agent

# Re-trigger binding
openstack server reboot --hard <SERVER>

Conclusion

A binding_failed port means no ML2 driver/agent on the target host could wire the port to its segment. The usual root causes:

1. The L2 agent (OVS/Linuxbridge) on the compute host is down or not heartbeating.
2. An ML2 mechanism/type driver mismatch between the network and the host’s agent.
3. The port’s physical_network has no bridge_mappings entry on that host.
4. The mapped bridge or provider interface does not exist.
5. An MTU or segmentation-id/range mismatch makes the segment unbindable.
6. A direct/macvtap vnic_type with no SR-IOV agent on the host.

Work the port’s reported segment and host first — the fix is almost always restoring an agent or aligning one host’s mappings with the rest of the fleet.