🚨 OpenStack Error Guide: 'Timeout waiting for vif plugging callback' — Fix Neutron/Nova VIF Plug

Overview

Timeout waiting for vif plugging callback is the error nova-compute raises when it plugs an instance’s virtual interface (VIF) and then waits for Neutron to confirm the port is wired into the data plane — but the confirmation (network-vif-plugged) never arrives within vif_plugging_timeout. Nova refuses to power on the guest until the network is proven ready, so the build fails.

The literal error you will see:

nova.exception.VirtualInterfaceCreateException: Virtual Interface creation failed
Timeout waiting for [('network-vif-plugged', 'a1b2c3d4-...')] for instance with vm_state building and task_state spawning.

It occurs during instance boot, unshelve, or live migration — anywhere Nova must attach a port and wait for Neutron’s L2 agent (OVS, Linuxbridge) or OVN to report the interface plugged. The instance usually lands in ERROR with Build of instance aborted. The tell is that Nova is healthy and libvirt created the domain; it is Neutron’s plug event that is missing.

Symptoms

• Instances fail to spawn with VirtualInterfaceCreateException after ~300s.
• nova-compute logs Timeout waiting for vif plugging callback.
• One compute host or one network affected while others build fine.

openstack server show <instance> -c status -c fault

| status | ERROR                                                                 |
| fault  | {'message': 'Virtual Interface creation failed', 'code': 500, ...}     |

docker logs nova_compute 2>&1 | grep -iE "vif plugging|VirtualInterfaceCreate" | tail -5

ERROR nova.compute.manager Timeout waiting for [('network-vif-plugged', 'a1b2c3d4-...')] for instance ...

Common Root Causes

1. Neutron L2 agent is down on the compute host

If the OVS or Linuxbridge agent isn’t running, nobody wires the port and no event is sent.

openstack network agent list --host compute-01 -c "Agent Type" -c Alive -c State
docker ps --filter name=neutron_openvswitch_agent --format '{{.Names}} {{.Status}}'

| Open vSwitch agent | XXX (dead) | UP |

An agent that is not :-) alive on the target host means the VIF will never be plugged there.

2. OVN: chassis not registered or ovn-controller stuck

In OVN deployments there is no per-host L2 agent; ovn-controller on the chassis programs flows. If it can’t reach the southbound DB, the port stays down.

docker exec ovn_controller ovn-sbctl --db=tcp:<vip>:6642 show | grep -A2 "Chassis \"compute-01\""
docker logs ovn_controller 2>&1 | tail -20

(empty output — chassis missing)

A missing chassis entry means ovn-controller never bound the port, so Nova’s os-vif plug never completes.

3. RabbitMQ gap drops the notification

The network-vif-plugged event travels over RabbitMQ. A messaging hiccup between Neutron and Nova can lose the notification even though the port is actually up.

openstack port show <port-id> -c status -c binding_vif_type
docker logs neutron_server 2>&1 | grep -iE "vif-plugged|<port-id>" | tail -5

| status           | ACTIVE   |
| binding_vif_type | ovs      |

If the port is ACTIVE but Nova still timed out, suspect a lost message rather than a plugging failure.

4. vif_plugging_timeout too short for a loaded host

Under boot storms, plugging is real but slow. The default timeout can expire before a busy agent finishes.

grep -E 'vif_plugging_timeout|vif_plugging_is_fatal' /etc/nova/nova.conf

vif_plugging_timeout = 300
vif_plugging_is_fatal = True

5. MTU / firewall driver / OVS bridge misconfiguration

A broken openvswitch_agent.ini (wrong bridge mappings, firewall driver mismatch) makes the agent fail to wire the port silently.

docker exec neutron_openvswitch_agent grep -E 'bridge_mappings|firewall_driver' \
  /etc/neutron/plugins/ml2/openvswitch_agent.ini
docker exec neutron_openvswitch_agent ovs-vsctl show | grep -iE 'error|br-int'

Bridge br-int
    Port "tapXXXX"
        Interface "tapXXXX"
            error: "could not open network device"

6. Nova and Neutron disagree on notifications

If [DEFAULT] notify_nova_on_port_status_changes is off in Neutron, or the nova auth section is wrong, Neutron never calls Nova back.

docker exec neutron_server grep -E 'notify_nova_on_port_status_changes|notify_nova_on_port_data_changes' \
  /etc/neutron/neutron.conf

notify_nova_on_port_status_changes = False

Diagnostic Workflow

Step 1: Confirm the agent/chassis on the target host

openstack network agent list --host <compute-host> -c "Agent Type" -c Alive
# OVN
docker exec ovn_controller ovn-sbctl --db=tcp:<vip>:6642 show | grep -i chassis

If the L2 agent is dead or the chassis is missing, that’s the cause.

Step 2: Check the port’s actual status

openstack port show <port-id> -c status -c binding_host_id -c binding_vif_type

ACTIVE port + Nova timeout points at a lost notification; DOWN port points at a real plugging failure.

Step 3: Read both logs around the same timestamp

docker logs nova_compute 2>&1 | grep -iE "vif plugging|<port-id>" | tail -10
docker logs neutron_server 2>&1 | grep -iE "<port-id>|vif-plugged" | tail -10
docker logs neutron_openvswitch_agent 2>&1 | grep -iE "<port-id>|error" | tail -10

Step 4: Verify Neutron-to-Nova notification config

docker exec neutron_server grep -E 'notify_nova_on_port_status_changes|^\[nova\]' -A6 \
  /etc/neutron/neutron.conf

Step 5: Inspect the OVS integration bridge

docker exec neutron_openvswitch_agent ovs-vsctl show | grep -iE 'error|tap'
docker exec neutron_openvswitch_agent ovs-ofctl dump-flows br-int | wc -l

Example Root Cause Analysis

A tenant reports every instance on compute-03 failing with Virtual Interface creation failed, while compute-01/02 are fine. nova-compute on that host:

ERROR nova.compute.manager Timeout waiting for [('network-vif-plugged', 'a1b2c3d4-...')] ...

The port itself is DOWN, so this is a real plug failure, not a lost message:

openstack port show a1b2c3d4-... -c status -c binding_host_id

| status          | DOWN       |
| binding_host_id | compute-03 |

Checking the OVS agent on compute-03:

openstack network agent list --host compute-03 -c "Agent Type" -c Alive

| Open vSwitch agent | XXX |

The agent is dead. Its log shows it crashed after an ovsdb connection loss following an OVS restart:

docker logs neutron_openvswitch_agent 2>&1 | tail -5

ERROR neutron.agent ... OVSDB Error: connection closed; agent exiting

Fix: restart the agent and confirm the chassis wires ports again:

docker restart neutron_openvswitch_agent
openstack network agent list --host compute-03 -c "Agent Type" -c Alive   # :-)
openstack server create ... # new build plugs successfully

Longer term, add a liveness alert on per-host agent state so a dead L2 agent pages before tenants notice.

Prevention Best Practices

• Alert on openstack network agent list liveness per host — a dead L2 agent or missing OVN chassis is the most common cause and is silent until a build fails.
• Monitor RabbitMQ health (see the MessagingTimeout guide); lost network-vif-plugged events trace back to the bus.
• Keep vif_plugging_is_fatal = True but size vif_plugging_timeout for your worst boot-storm; failing fast on a genuinely broken port is safer than booting a guest with no network.
• Verify notify_nova_on_port_status_changes = True and the Neutron [nova] auth section after every upgrade or credential rotation.
• Validate bridge_mappings and firewall_driver consistency across all compute hosts with config management.
• For OVN, monitor ovn-controller connectivity to the southbound DB and chassis registration.
• Drop the paired Nova/Neutron log excerpts into the free incident assistant to separate a lost-message case from a real plug failure, and see more OpenStack guides.

Quick Command Reference

# Which host, and is its agent/chassis alive?
openstack network agent list --host <compute-host> -c "Agent Type" -c Alive
docker exec ovn_controller ovn-sbctl --db=tcp:<vip>:6642 show | grep -i chassis

# Real plug failure vs lost message?
openstack port show <port-id> -c status -c binding_host_id -c binding_vif_type

# Paired logs
docker logs nova_compute 2>&1 | grep -iE "vif plugging|<port-id>" | tail -10
docker logs neutron_server 2>&1 | grep -iE "<port-id>|vif-plugged" | tail -10
docker logs neutron_openvswitch_agent 2>&1 | grep -iE "<port-id>|error" | tail -10

# Notification config
docker exec neutron_server grep -E 'notify_nova_on_port_status_changes' /etc/neutron/neutron.conf
grep -E 'vif_plugging_timeout|vif_plugging_is_fatal' /etc/nova/nova.conf

# OVS bridge health
docker exec neutron_openvswitch_agent ovs-vsctl show | grep -iE 'error|tap'

# Recover
docker restart neutron_openvswitch_agent

Conclusion

Timeout waiting for vif plugging callback means Nova plugged the interface and never heard back from Neutron that the port was wired. The instance fails because Nova deliberately refuses to boot a guest with an unconfirmed network. Typical root causes:

1. The Neutron L2 agent (OVS/Linuxbridge) is down on the target compute host.
2. In OVN, the chassis isn’t registered or ovn-controller can’t reach the southbound DB.
3. A RabbitMQ gap dropped the network-vif-plugged notification.
4. vif_plugging_timeout is too short for a loaded host during a boot storm.
5. OVS bridge/MTU/firewall-driver misconfiguration prevents wiring.
6. Neutron isn’t configured to notify Nova on port status changes.

Check the port’s real status first: an ACTIVE port with a Nova timeout is a lost message; a DOWN port is a genuine plugging failure — and that distinction tells you whether to look at RabbitMQ or at the L2 agent.