neutron — Errors

Errors — neutron — branch stable/2026.2

Branch stable/2026.2 @ eef1a0f7ee36 — repository https://opendev.org/openstack/neutron — analysed on 2026-10-28 Library: neutron-lib stable/2026.2 @ 1ee72052 (cited as neutron-lib:)

Scope: ML2/OVN reference profile (see 01-rest-api_stable-2026.2.md). The catalogue of § 5 is generated (_rewrite/tools/errors02.py) and limited to exceptions raised in the in-scope code (agents other than the OVN metadata agent, and the BGP, EVPN, local IP, NDP proxy, metering and conntrack-helper services, are excluded).

1. Error body

Every error produced by Neutron code has the same JSON body:

{"NeutronError": {"type": "<exception class name>", "message": "<formatted message>", "detail": ""}}

built by get_exception_data (neutron/api/api_common.py:520-532). type is the class name, which clients use to discriminate errors (Nova checks type for PortBindingAlreadyExists, IpAddressGenerationFailure…; the openstacksdk maps it to exceptions). detail is always empty. The message is translated when Accept-Language names an available locale (neutron/pecan_wsgi/hooks/translation.py:28-35, neutron/api/v2/resource.py:66).

Exceptions to the format:

• NotImplementedError → 501 with key NotImplementedError instead of NeutronError (neutron/api/api_common.py:500-509).
• Errors raised before Neutron code (keystonemiddleware 401, catch_errors 500, Routes 405) do not use this body, except the 405s and 404s that pecan and the extension middleware produce (they are converted, type is the webob class name such as HTTPMethodNotAllowed, HTTPNotFound).
• A policy failure in pecan's after hook sets a 404 body {"type": "HTTPNotFound", "message": "The resource could not be found.", "detail": ""} without the NeutronError wrapper (neutron/pecan_wsgi/hooks/policy_enforcement.py:195-210). Only networks, subnets, ports and subnetpools can produce it.

2. Exception → HTTP translation

One table for both layers: FAULT_MAP (neutron-lib:neutron_lib/api/faults.py:19-29), applied by convert_exception_to_http_exc (neutron/api/api_common.py:449-517), called by the pecan ExceptionTranslationHook (neutron/pecan_wsgi/hooks/translation.py:27-43) and by the legacy Resource wrapper (neutron/api/v2/resource.py:97-110).

Rules that change what the client sees:

• Multiple errors. MultipleExceptions (and ML2's MechanismDriverError, its subclass, neutron/plugins/ml2/common/exceptions.py:23) are unwrapped: if all inner errors map to the same status, that status is returned with the messages joined by \n; otherwise **409 Conflict** whose message lists HTTP <code> <type>: <message> per inner error (neutron/api/api_common.py:451-480). So an OVN driver error during a postcommit reaches the client with the status of the underlying exception, not as "MechanismDriverError".
• Hiding. A policy refusal on GET, PUT or DELETE of an object the caller may not even read becomes 404 "The resource could not be found." (neutron/api/v2/base.py:396-400, 673-683, 588-598; neutron/pecan_wsgi/hooks/policy_enforcement.py:131-146). A refusal on POST, or on an object the caller may read, stays 403. List calls drop the forbidden items silently.
• Network ownership. The legacy controller returns 404 when a non-admin creates a subnet or port on a network of another project (neutron/api/v2/base.py:777-796), but subnets and ports are served by pecan, which does not call this check: there the policy rules (rule:network_owner) apply and give 403/404 [inferred: dead code for the API].
• 412. RevisionNumberConstraintFailed (If-Match mismatch) is a webob.exc.HTTPPreconditionFailed (neutron/services/revisions/revision_plugin.py:324-330).
• Logging. 4xx are logged at INFO as <action> failed (client error): <exc>; 5xx at ERROR with the traceback (neutron/api/v2/resource.py:100-109, neutron/pecan_wsgi/hooks/translation.py:38-42).

3. Errors raised directly as HTTP statuses (no exception class)

4. OVN-specific failure paths

5. Catalogue of exceptions raised in scope

Columns: HTTP status computed with the real FAULT_MAP; message template; up to four raise sites with the enclosing function (the function name is the shortest description of the situation; the main situations are described in business terms in 01 § 4); class definition. Exceptions raised only by background code (maintenance, OVSDB events, agents) never reach a client as an HTTP status: they are logged, see § 6.

6. Asynchronous errors and key log messages

There is no ERROR status in the ML2/OVN flows of this scope. The metadata agent's failures are seen by the VM as an HTTP status on 169.254.169.254 (404, 403, 500, 503) and never reach the Neutron API: background failures are only visible in logs, in a port stuck in DOWN, or in binding:vif_type = binding_failed.

Timeouts to know: [ovn]/ovsdb_connection_timeout 180 s per OVSDB transaction; [DEFAULT]/rpc_response_timeout (60 s) for RPC calls made by agents; Nova event send retried for 1 s only; DB retries up to 20 attempts.

Source: reverse-spec-neutron/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.