Errors — neutron-fwaas — branch stable/2026.2
Branch
stable/2026.2@5303a4deed1e— repository https://opendev.org/openstack/neutron-fwaas — analysed on 2026-10-28.neutron-lib:= neutron-libstable/2026.2@1ee72052251a;neutron:= neutronstable/2026.2@eef1a0f7ee36.
Most FWaaS exceptions are defined in neutron-lib (neutron-lib:neutron_lib/exceptions/firewall_v2.py). neutron-fwaas adds:
- two exceptions for the default resources (
neutron_fwaas/db/firewall/v2/firewall_db_v2.py:54); - one for driver support (
neutron_fwaas/common/exceptions.py:22); - three in the OVN driver (
neutron_fwaas/services/firewall/service_drivers/ovn/exceptions.py:20); - two in the OVS L2 driver;
- three in logging;
- two in migrations.
The observed (operation, status, type, message) combinations of the unit-test run are listed in _rewrite/observed-errors_stable-2026.2.md.
Exception → HTTP translation
Neutron translates exceptions in one place, convert_exception_to_http_exc (neutron:neutron/api/api_common.py:449), with neutron-lib's FAULT_MAP (neutron-lib:neutron_lib/api/faults.py:19):
| Base class | HTTP |
|---|---|
NotFound | 404 |
Conflict, InUse | 409 |
BadRequest (including InvalidInput) | 400 |
NotAuthorized, PolicyNotAuthorized, InvalidScope | 403 |
ServiceUnavailable | 503 |
netaddr.AddrFormatError | 400 |
other NeutronException | 500, with the exception message in the body |
NotImplementedError | 501 |
anything else (ovsdbapp, SQLAlchemy, RuntimeError, ValueError…) | 500 "Request Failed: internal server error while processing your request." (neutron:neutron/api/api_common.py:512) |
The body is always {"NeutronError": {"type": "<class name>", "message": "<text>", "detail": ""}} (neutron:neutron/api/api_common.py:520). Clients (openstacksdk, neutronclient) use type to tell errors apart.
Names that mislead. FirewallPolicyConflict and FirewallRuleSharingConflict derive from NotFound and are returned as 404, not 409 (neutron-lib:neutron_lib/exceptions/firewall_v2.py:54, neutron-lib:neutron_lib/exceptions/firewall_v2.py:64). MechanismDriverNotFound (OVN driver misconfigured) is also a 404 (neutron_fwaas/services/firewall/service_drivers/ovn/exceptions.py:20).
Catalogue
| Exception | HTTP | Message (template) | Situation | Raised at | Seen by the client as |
|---|---|---|---|---|---|
| FirewallGroupNotFound | 404 | "Firewall group %(firewall_id)s could not be found." | the group id does not exist (the plugin also uses it to make DELETE idempotent) | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:848 | 404 NeutronError |
| FirewallGroupInUse | 409 | "Firewall group %(firewall_id)s is still active." | DELETE of a group that still has ports | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:332 | 409 |
| FirewallGroupInPendingState | 409 | "Operation cannot be performed since associated firewall group %(firewall_id)s is in %(pending_state)s." | PUT of a group, or of a policy/rule used by a group, while that group is PENDING_CREATE/UPDATE/DELETE (agent driver: waiting for the agents) | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:97 | 409 |
| FirewallGroupPortInvalid | 409 | "Port %(port_id)s of firewall group is invalid." | a port in ports is neither a router interface nor a compute port (DHCP, gateway, unowned…) | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:169 | 409 |
| FirewallGroupPortNotSupported (neutron-fwaas copy) | 409 | "Port %(port_id)s is not supported by firewall driver '%(driver_name)s'." | router port refused by is_supported_l3_port, or compute port refused by is_supported_l2_port. With OVN: every VM port | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:161, neutron_fwaas/services/firewall/fwaas_plugin_v2.py:166 (class neutron_fwaas/common/exceptions.py:22) | 409 |
| FirewallGroupPortInUse | 409 | "Port(s) %(port_ids)s provided already associated with other firewall group(s)." | (1) another group of the same project already holds the port; (2) the unique key port_id fires (port held by a group of another project) | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:207, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:596 | 409; message shows a Python list (['<uuid>']) |
| FirewallGroupCannotRemoveDefault | 409 | "Deleting default firewall group not allowed." | a non-admin deletes the default group | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:813 | 409 |
| FirewallDefaultParameterExists | 409 | "Operation cannot be performed since '%(name)s' is a reserved name for %(resource_type)s." | creating, or renaming to, a group named default; creating a policy named default ingress/default egress | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:832, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:841 | 409 |
| FirewallDefaultObjectUpdateRestricted | 409 | "Operation cannot be performed on default object '%(resource_id)s' of type %(resource_type)s." | (1) PUT on the default group of a forbidden attribute (member: name, description, admin_state_up, policies; admin: name); (2) any PUT on a default policy, with resource_type wrongly set to "Firewall Group" | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:762, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:838 | 409 |
| FirewallPolicyNotFound | 404 | "Firewall policy %(firewall_policy_id)s could not be found." | unknown policy id (GET/PUT/DELETE, group creation/update, insert/remove) | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:561 | 404 |
| FirewallPolicyInUse | 409 | "Firewall policy %(firewall_policy_id)s is being used." | (1) DELETE of a policy used by any group; (2) un-sharing a policy used by a group of another project | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:550, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:553, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:467 | 409 |
| FirewallPolicyConflict | 404 | "Operation cannot be performed since firewall policy %(firewall_policy_id)s for your project could not be found. Please confirm if the firewall policy exists and is shared." | a group references an unshared policy of another project | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:141 | 404 |
| FirewallPolicySharingConflict | 409 | "Operation cannot be performed. Before sharing firewall policy %(firewall_policy_id)s, share associated firewall rule %(firewall_rule_id)s." | shared: true on a policy whose current rules are not all shared | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:443 | 409 |
| FirewallRuleSharingConflict | 404 | "Operation cannot be performed since firewall policy %(firewall_policy_id)s could not find the firewall rule %(firewall_rule_id)s. Please confirm if the firewall rule exists and is shared." | a shared policy (or one made shared in the same PUT) gets an unshared rule in firewall_rules | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:421, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:425 | 404 |
| FirewallRuleNotFound | 404 | "Firewall rule %(firewall_rule_id)s could not be found." | unknown rule id; unknown id in a policy's firewall_rules; firewall_rule_id of insert/remove not a UUID (message then shows the raw value, for example "None" or "foo") | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:74, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:417, neutron_fwaas/services/firewall/fwaas_plugin_v2.py:253 | 404 |
| FirewallRuleInUse | 409 | "Firewall rule %(firewall_rule_id)s is being used." | DELETE of a rule still in a policy | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:320 | 409 |
| FirewallRuleNotAssociatedWithPolicy | 400 | "Firewall rule %(firewall_rule_id)s is not associated with firewall policy %(firewall_policy_id)s." | remove_rule of a rule not in the policy; insert_before/insert_after naming a rule not in the policy | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:175 | 400 |
| FirewallRuleAlreadyAssociated | 409 | "Operation cannot be performed since firewall rule %(firewall_rule_id)s is already associated with firewall policy %(firewall_policy_id)s." | insert_rule of a rule already in the policy | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:161 | 409 |
| FirewallRuleConflict | 409 | "Operation cannot be performed since firewall rule %(firewall_rule_id)s is not shared and belongs to another project %(project_id)s." | a policy receives (create, PUT or insert) an unshared rule of another project | neutron_fwaas/db/firewall/v2/firewall_db_v2.py:119, neutron_fwaas/db/firewall/v2/firewall_db_v2.py:432 | 409; reveals the other project's id |
| FirewallRuleInfoMissing | 400 | "Missing rule info argument for insert/remove rule operation." | insert/remove body without firewall_rule_id | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:250 | 400 |
| FirewallRuleInvalidICMPParameter | 400 | "%(param)s are not allowed when protocol is set to ICMP." (param = "Source, destination port") | ports with a protocol other than tcp/udp, including sctp (the message says ICMP whatever the protocol) | neutron_fwaas/common/utils.py:29 | 400 |
| FirewallRuleWithPortWithoutProtocolInvalid | 400 | "Source/destination port requires a protocol." | ports without a protocol | neutron_fwaas/common/utils.py:33 | 400 |
| FirewallRuleInvalidPortValue | 400 | "Invalid value for port %(port)s." | port range min > max reaching the plugin (normally caught first by the API validator, which answers 400 HTTPBadRequest "Invalid input for source_port. Reason: First port in a port range must be lower than the second port.") | neutron_fwaas/common/utils.py:54 | 400 |
| FirewallIpAddressConflict | 400 | "Invalid input - IP addresses do not agree with IP Version." | an address of the other IP version than ip_version | neutron_fwaas/common/utils.py:48 | 400 |
| FirewallInternalDriverError | (500) | "%(driver)s: Internal driver error." | iptables or conntrack failure on the agent (LookupError, RuntimeError in iptables_manager); never reaches the API | neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/iptables_fwaas_v2.py:90, neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/iptables_fwaas_v2.py:135, neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/iptables_fwaas_v2.py:156, neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/iptables_fwaas_v2.py:188 | group status ERROR (see below) |
| MechanismDriverNotFound | 404 | "None of the supported mechanism drivers found: %(mechanism_drivers)s. Check your configuration." | OVN driver configured while ML2 has neither the ovn nor the ovn-sync mechanism driver; raised at the first OVN access (group create/update/delete, policy/rule changes) | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:68 | 404 on a write (misleading) |
| OperatorNotSupported | 500 | "The operator \"%(operator)s\" is not supported. Valid operators are: %(valid_operators)s." | internal misuse of process_rule_for_pg (op not add/del/mod); unreachable from the API | neutron_fwaas/services/firewall/service_drivers/ovn/acl.py:187 | 500 with message |
| ProtocolNotSupported | 500 | "The protocol \"%(protocol)s\" is not supported. …" | defined, never raised (dead) | neutron_fwaas/services/firewall/service_drivers/ovn/exceptions.py:25 | — |
| ValueError "Unkown action" | 500 | "Unkown action: %s" | rule action outside allow/deny/reject reaching the OVN ACL builder; unreachable through the API | neutron_fwaas/services/firewall/service_drivers/ovn/acl.py:123 | 500 generic |
| OVSFWaaSPortNotFound | (agent) | "Port %(port_id)s is not managed by this agent." | the OVS L2 driver gets a port that is not on the integration bridge | neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/firewall.py:308 (class neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/exceptions.py:21) | logged; group ERROR through the L2 extension |
| OVSFWaaSTagNotFound | (agent) | "Cannot get vlan tag for port %(port_id)s." | the port has no local VLAN tag yet | neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/firewall.py:321 (class neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/exceptions.py:25) | same |
| FWGIsNotReadyForLogging | 400 | "Firewall group %(fwg_id)s is not ready for logging because of %(fwg_status)s status." | POST /v2.0/log/logs with resource_type=firewall_group on a group that is not ACTIVE (or whose port's group is not) | neutron_fwaas/services/logapi/fwg_validate.py:37, neutron_fwaas/services/logapi/fwg_validate.py:78 | 400 on the Neutron logging API |
| TargetResourceNotAssociated | 400 | "Target resource %(target_id)s is not associated with any firewall group." | logging target_id port with no group | neutron_fwaas/services/logapi/fwg_validate.py:73 | 400 |
| PortIsNotReadyForLogging | 400 | "Target resource %(target_id)s is not ready for logging because of %(port_status)s status." | logging target_id port not ACTIVE | neutron_fwaas/services/logapi/fwg_validate.py:65 | 400 |
| DuplicateDefaultFirewallGroup | (migration) | "Duplicate Firewall group found named 'default'. Database cannot be upgraded. …" | neutron-db-manage sanity check before the Queens migration that creates default_firewall_groups | neutron_fwaas/db/migration/alembic_migrations/versions/queens/expand/876782258a43_create_default_firewall_groups_table.py:67 (class line 38) | migration aborts |
| DuplicatePortRecordinFirewallGroupPortAssociation | (migration) | "Duplicate port(s) %(port_id)s records exist in firewall_group_port_associations_v2 table. …" | sanity check before adding the unique key on port_id | neutron_fwaas/db/migration/alembic_migrations/versions/queens/expand/f24e0d5e5bff_uniq_firewallgroupportassociation0port.py:59 (class line 41) | migration aborts |
| OverQuota (Neutron) | 409 | "Quota exceeded for resources: …" | more than quota_firewall_group/policy/rule resources in the project | neutron:neutron/api/v2/base.py:491 | 409 |
| HTTPBadRequest (Neutron) | 400 | "Unable to find '<resource>' in request body", "Bulk operation not supported", "Invalid input for <attr>. Reason: …" | malformed body, list body, attribute validator failure | neutron:neutron/api/v2/base.py:712 | 400, type = HTTPBadRequest |
| HTTPNotFound (Neutron) | 404 | "The resource could not be found." | resource not visible to the caller (policy) | neutron:neutron/api/v2/base.py:400 | 404 |
Exceptions defined but never raised by neutron-fwaas: FirewallGroupPortInvalidProject (neutron-lib), ProtocolNotSupported, and the neutron-lib copy of FirewallGroupPortNotSupported (shadowed by neutron_fwaas/common/exceptions.py:22; same message and status).
Unexpected 500s
| Situation | Where | What the client sees |
|---|---|---|
| OVSDB transaction fails during group create post-commit (NB unreachable, constraint error) | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:228 | 500 generic. The Port_Group is deleted, and the group row is rolled back with the plugin's transaction, which the post-commit hook still runs in (neutron_fwaas/services/firewall/fwaas_plugin_v2.py:307). The default group, created in a separate transaction, stays [inferred] |
| OVSDB error during group update, policy update, rule update, insert/remove | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:283, neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:162 | 500 generic. The hooks run inside the plugin's DB transaction, so the DB change is rolled back. The OVSDB transactions already committed in the same request are not: a Port_Group recreated, or the ACLs of the groups processed before the failing one, stay changed, and the DB and OVN diverge until the next neutron-ovn-db-sync-util --sync_mode repair [inferred] |
| OVSDB error in pre-commit (create group: Port_Group creation; delete group: Port_Group deletion) | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:206, neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:307 | 500 generic. The DB transaction is rolled back. create_pg_for_fwg commits its own OVSDB transaction, so a Port_Group can remain without a group; likewise, if the DB commit itself fails after a successful OVN create or delete [inferred] |
Core plugin get_port raises PortNotFound for an unknown port in ports | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:157 | 404 PortNotFound (Neutron) |
Asynchronous errors (agent driver)
These never become an HTTP status. They show up in the group's status and in agent logs.
| Status | Set by | Situation |
|---|---|---|
ERROR | set_firewall_group_status RPC from the L3 agent (neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:408, neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:471, neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:546) | the iptables driver raised FirewallInternalDriverError |
ERROR | L2 extension (neutron_fwaas/services/firewall/service_drivers/agents/l2/fwaas_v2.py:157, neutron_fwaas/services/firewall/service_drivers/agents/l2/fwaas_v2.py:300) | OVS flow programming failed, or any exception in the handler |
ERROR | server sanitising (neutron_fwaas/services/firewall/service_drivers/agents/agents.py:58) | the agent sent a status other than ACTIVE, DOWN, INACTIVE |
ERROR | server (neutron_fwaas/services/firewall/service_drivers/agents/agents.py:83) | an agent reported firewall_group_deleted for a group that was not PENDING_DELETE/ERROR ("unexpectedly deleted by agent") |
stuck PENDING_CREATE / PENDING_UPDATE | — | no agent answered: the fanout cast reached no L3 agent hosting the router, or the status RPC failed (MessagingTimeout). The agent then sets services_sync_needed, but nothing ever consumes that flag (05 § "process_services_sync"). Every PUT on the group, its policies or rules returns 409 FirewallGroupInPendingState |
Key log messages
| Level | Message | Situation | Where |
|---|---|---|---|
| WARNING | "Multiple drivers configured for Firewall v2, although running multiple drivers in parallel is not yet supported" | several FIREWALL_V2 service providers | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:65 |
| INFO | "Firewall v2 Service Plugin using Service Driver: %s" | plugin start | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:61 |
| WARNING | "Cannot found default firewall group of project %s" | auto-attachment of a new VM port: no default group | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:288 |
| WARNING | "Port %s has been already associated with default firewall group %s and skip association" | auto-attachment race | neutron_fwaas/services/firewall/fwaas_plugin_v2.py:299 |
| ERROR | "Failed to create_firewall_group_postcommit." | OVN post-commit failure (followed by the exception) | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:232 |
| WARNING | "Cannot find Port_Group with name: %s" | OVN rule update/delete for a group without Port_Group | neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:187 |
| WARNING | "Number of Port Groups to sync: %d, remove: %d" (+ the two lists) | OVN DB sync found differences | neutron_fwaas/services/firewall/service_drivers/ovn/ovn_db_sync.py:132 |
| WARNING | "OVN FWaaS driver is required for OVN DB sync" | sync run with another driver | neutron_fwaas/services/firewall/service_drivers/ovn/ovn_db_sync.py:64 |
| WARNING | "Firewall %(fwg)s unexpectedly deleted by agent, status was %(status)s" | agent firewall_group_deleted out of sequence | neutron_fwaas/services/firewall/service_drivers/agents/agents.py:80 |
| WARNING | "Doesn't support hybrid port at the moment" / "Doesn't support vif type %s" | VM port refused by the agent driver | neutron_fwaas/services/firewall/service_drivers/agents/agents.py:191, neutron_fwaas/services/firewall/service_drivers/agents/agents.py:193 |
| ERROR (exception) | "FWaaS driver error in create_firewall_group for firewall group: %(fwg_id)s" (and update/delete variants) | iptables failure on the L3 agent | neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:405 |
| ERROR (exception) | "FWaaS RPC failure in create_firewall_group for firewall group: %(fwg_id)s" (and update/delete variants) | status RPC to the server failed | neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:415 |
| ERROR | "FWaaS plugin is configured in the server side, but FWaaS is disabled in L3-agent." then exit 1 | dead check: neutron_service_plugins is always None | neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:124 |
| WARNING | "Port(s) %s is associated with more than one firewall group(s)." | router sync found a port in two groups | neutron_fwaas/services/firewall/service_drivers/agents/l3reference/firewall_l3_agent_v2.py:295 |
| ERROR (exception) | "Failed to create firewall: %s" / "Failed to update firewall: %s" / "Failed to delete firewall: %s" | iptables manager failure | neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/iptables_fwaas_v2.py:89 |
| WARNING | "No Local VLAN found in network %s" | L2 OVS: port's network not yet wired | neutron_fwaas/services/firewall/service_drivers/agents/l2/fwaas_v2.py:208 |
| ERROR | "Initializing port %s that was already initialized." | OVS L2 driver re-initialisation | neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/firewall.py:367 |
Source: reverse-spec-neutron-fwaas/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.