← Production Guide · Networking
PG-38 · Binding failed for port?¶

Operational lesson. Nova names the host. Neutron must find a live agent, with the right mappings, under that exact name.
The memo as text¶
Situation. A build goes to ERROR, or a live migration is refused at once. Neutron could not bind the port on that host.
First checks (read-only):
- The port, if it still exists:
openstack port show <port> -c binding_host_id -c binding_vif_type - Network type, physical network:
openstack network show <network> | grep provider: - Agents under that host name:
openstack network agent list --host <compute> - What the server log says:
grep <port-id> neutron-server.log | grep -iE 'bind|refusing'
Think before acting:
- ⛔ Avoid. Changing Nova's
hoston a compute that has instances. Change the Neutron side to the name Nova already uses. - ⚠️ State-changing. With OVN on Kolla-Ansible, changing the chassis hostname restarts
openvswitch_vswitchd: instances there can lose the network briefly.
Go deeper¶
This memo is a memory aid. The procedure, with every command, its risk warning and its limits, is in the runbook:
- Instance build or live migration fails with "Binding failed for port". Neutron could not bind the port on that host ·
drafton 2026.1 · highest risk in the page: state-changing - Instance stuck in BUILD, then ERROR after vif_plugging_timeout ·
lab-verifiedon 2026.1 · highest risk in the page: state-changing
Where this holds. The runbook is a draft, written from the Neutron and Nova 2026.1 sources. A dead agent, mismatched host names (simulated) and a missing mapping (symptom only) were reproduced on an ML2/OVS Kolla-Ansible lab; the ML2/OVN parts and an unsupported network type were not. Ports already bound keep working; ports Nova created for a build are deleted when it fails. SR-IOV, hardware offload, routed provider networks and Ironic ports are not covered.
LinkedIn kit¶
- Image:
dist/pg-38-binding-failed-for-port.png(1080 × 1350) - Post title: "Binding failed for port": start with the Neutron server log
A build ends in ERROR with "Binding failed for port <id>, please check neutron logs for more information." Or a live migration is refused before it starts, sometimes as "No valid host".
For once the message points the right way: start with the Neutron server log, for that port ID.
When Nova allocates or moves a port, it gives Neutron a host name. Neutron then asks each mechanism driver to bind the port on that host. Three usual refusals:
→ the agent on that host is dead, or was renamed and is alive under another name
→ no agent or chassis is registered under that exact name: a short name on one side, an FQDN on the other
→ the host has no bridge mapping for the network's physical network
With ML2/OVS, the last two are only logged at debug level: the agent list and the network type tell them apart.
One rule when names differ: change the Neutron side, never Nova's host on a compute that has instances.
Source runbook status: draft.
Runbook: https://github.com/OzarLand/ozarland-academy/blob/main/docs/runbooks/networking/port-binding-failed.md
More memos: https://github.com/OzarLand/ozarland-academy/tree/main/docs/production
#OpenStack #Neutron #Nova #Networking #CloudOperations #OzarLand
Source: binding-failed-for-port.yml. Found an error, or does your platform behave differently? Open an issue or see CONTRIBUTING.