Skip to content

← Production Guide · Networking

PG-38 · Binding failed for port?

Binding failed for port? Operational lesson: Nova names the host. Neutron must find a live agent, with the right mappings, under that exact name.

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):

  1. The port, if it still exists: openstack port show <port> -c binding_host_id -c binding_vif_type
  2. Network type, physical network: openstack network show <network> | grep provider:
  3. Agents under that host name: openstack network agent list --host <compute>
  4. What the server log says: grep <port-id> neutron-server.log | grep -iE 'bind|refusing'

Think before acting:

  • ⛔ Avoid. Changing Nova's host on 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:

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

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.