🚨 OpenStack Error Guide: 'neutron-l3-agent router namespace missing' connectivity loss

Exact Error Message

2026-06-27 11:42:33.901 8 ERROR neutron.agent.l3.agent [-] Failed to process compatible router:
9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0
2026-06-27 11:42:33.901 8 ERROR neutron.agent.l3.agent Traceback (most recent call last):
2026-06-27 11:42:33.901 8 ERROR neutron.agent.l3.agent   File ".../neutron/agent/l3/agent.py", line 706, in _process_router_update
2026-06-27 11:42:33.901 8 ERROR neutron.agent.l3.agent     ip = ip_lib.IPWrapper(namespace=ns_name)
2026-06-27 11:42:33.901 8 ERROR neutron.agent.l3.agent neutron.privileged.agent.linux.ip_lib.NetworkNamespaceNotFound:
Network namespace qrouter-9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0 could not be found.

You may also see, from a host shell:

# ip netns exec qrouter-9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0 ip a
Cannot open network namespace "qrouter-9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0": No such file or directory

What the Error Means

Neutron’s L3 agent realizes each routed network as a Linux network namespace named qrouter-<router-id>. That namespace holds the router’s internal (qr-) and external (qg-) interfaces, the iptables NAT rules for floating IPs, and the default route to the external gateway. When the agent tries to program a router but the qrouter- namespace does not exist on the node, every operation against it fails and tenants behind that router lose north-south connectivity.

The namespace can vanish for several reasons: the l3-agent died and the namespace was cleared, a node rebooted and the agent has not yet rebuilt state, the OVS integration/external bridge is missing so interface plugging fails, or the router was rescheduled to a different agent and the old node still references it. The error is a symptom — the real question is why the agent cannot (re)create or find the namespace.

Common Causes

• l3-agent is down or wedged — without a running agent the namespaces are never (re)created after a reboot.
• Node reboot before agent resync — namespaces are not persistent; the agent must rebuild them on startup and may be mid-resync.
• Missing OVS bridge (br-int or br-ex) — the agent cannot plug qr-/qg- interfaces, so namespace setup aborts.
• Router rescheduled / agent removed — the router was moved to another L3 agent (or its agent was deleted), leaving stale references.
• External network / gateway misconfiguration — the qg- interface cannot attach to br-ex, leaving the router half-built.
• neutron-ovs-cleanup or manual ip netns delete ran and wiped the namespace out from under the agent.
• DVR mismatch — on a Distributed Virtual Router setup, the namespace lives on compute nodes (snat-/qrouter-), and you are looking on the wrong node.

How to Reproduce the Error

In a lab, the cleanest reproduction is to delete the namespace while leaving the router configured:

1. Create a router with an external gateway and an attached subnet; confirm ip netns list shows qrouter-<id> on the network node.
2. Stop the l3-agent so it cannot immediately rebuild.
3. Delete the namespace by hand to simulate a reboot or cleanup race.

The next time the agent processes that router (or you run any ip netns exec qrouter-<id> ...), the NetworkNamespaceNotFound error appears. Restarting the agent with a missing br-ex reproduces the bridge-plug variant.

Diagnostic Commands

All read-only. Start with the agent and router state from the API:

# Is the L3 agent alive and which router lives where?
openstack network agent list --agent-type l3
openstack network agent show <l3-agent-id>
openstack router show 9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0 -c admin_state_up -c status -c external_gateway_info
openstack network agent list --router 9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0

On the node hosting the agent, inspect namespaces, bridges, and logs:

# Kolla-Ansible
docker exec neutron_l3_agent ip netns list | grep qrouter
docker exec openvswitch_vswitchd ovs-vsctl list-br
docker logs neutron_l3_agent 2>&1 | grep -i "NetworkNamespaceNotFound\|Failed to process" | tail

# Traditional packages
ip netns list | grep qrouter
ovs-vsctl list-br
journalctl -u neutron-l3-agent | grep -i "NetworkNamespaceNotFound\|Failed to process" | tail

br-int
br-ex
br-tun

If br-ex is missing from ovs-vsctl list-br, the external interface cannot be plugged — that is your root cause.

Step-by-Step Resolution

1. Verify the L3 agent is up and alive. If openstack network agent list shows the agent XXX (down), bring it back first:

   docker restart neutron_l3_agent          # Kolla-Ansible
   systemctl restart neutron-l3-agent       # Traditional

   A healthy agent rebuilds missing qrouter- namespaces automatically on its next sync.

2. Confirm the router is scheduled to this agent. Use openstack network agent list --router <id>. If it is on a different agent, you are debugging the wrong node — switch to the host that actually owns the router.

3. Check that br-int and br-ex exist. If br-ex is missing, recreate it and re-add the provider uplink per your deployment’s bridge mapping, then restart the agent so it can plug the qg- interface.

4. Force a clean reschedule if the namespace still will not build. Remove the router from the stuck agent and let Neutron reschedule it:

   openstack network agent remove router <l3-agent-id> 9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0
   openstack network agent add router <healthy-l3-agent-id> 9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0

5. Validate the namespace and connectivity once rebuilt:

   # Kolla-Ansible
   docker exec neutron_l3_agent ip netns exec qrouter-9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0 ip a
   # Traditional
   ip netns exec qrouter-9c4f1a2b-7d33-4e10-bb21-8a2c1d4e55f0 ip route

   You should see the qr- and qg- interfaces and a default route via the external gateway.

6. For DVR deployments, remember the snat- namespace lives on the centralized/network node while qrouter- namespaces also appear on compute nodes. Check the correct node before assuming the namespace is truly gone.

Prevention and Best Practices

• Run at least two L3 agents and use HA routers so a single agent death does not strand tenant traffic.
• Monitor openstack network agent list and alert when any L3 agent reports down — that is the leading indicator of namespaces about to disappear.
• Avoid running neutron-ovs-cleanup or ip netns delete on a live network node; reserve them for maintenance windows with the agent stopped.
• Verify bridge mappings (br-ex and provider bridges) survive reboots by pinning them in your OVS/host configuration, not just creating them at runtime.
• After any node reboot, confirm the L3 agent finished its resync before declaring the host healthy.

Related Errors

• NetworkNamespaceNotFound: Network namespace qdhcp-<id> could not be found — the DHCP-agent equivalent for qdhcp- namespaces.
• Failed to process compatible router without a traceback — often an OVS bridge plug failure rather than a missing namespace.
• Router <id> is not hosted by any L3 agent — scheduling failure, see our /categories/openstack/ networking guides.
• qg- interface not found — the external gateway port was never plugged into br-ex.

Frequently Asked Questions

Will restarting the l3-agent fix the missing namespace? Usually yes. The agent rebuilds qrouter- namespaces from the database on startup, provided the OVS bridges it needs (br-int, br-ex) exist. If a bridge is missing, fix that first.

Do I lose all tenant connectivity when the namespace is gone? North-south (external/floating-IP) traffic for routers in that namespace stops. East-west traffic that does not transit the router may continue.

Why does the namespace disappear after a reboot? Network namespaces are not persistent across reboots. They are recreated by the agent at startup, so a brief gap during resync is expected — a permanent gap means the agent is unhealthy.

On DVR, why do I not see the namespace on the network node? With DVR, routing is distributed: qrouter- namespaces live on each compute node hosting affected VMs, and only the snat- namespace is centralized. Check the compute node hosting the workload.

Is it safe to delete a stale qrouter namespace manually? Only with the agent stopped and after confirming the router is rescheduled elsewhere. Deleting it under a live agent invites a race that recreates the same error.