About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.
A bad VLAN push is three failures stacked on one bridge. Ports can be in the wrong VLANs. Untagged frames can land in VLAN 1 because a line was omitted and the default filled it in. The gateway, which is a switch virtual interface and not the bridge itself, can be missing or refused. Fixing one of those and calling the VLAN restored leaves hosts that pass traffic inside the wrong broadcast domain, or hosts that can reach each other and cannot reach their gateway.
Cumulus Linux 5.15 documents a VLAN-aware bridge as one bridge, one spanning-tree instance, and a list of allowed VLANs plus a port VLAN ID on each member. The port VLAN ID is the primary VLAN identifier, or native VLAN: the VLAN used for untagged frames. The switch virtual interface is a separate interface, with its own address. The page also says not to put the management port in that bridge, because the bridge then does not work correctly and disrupts management access.
This article uses that page as the concrete model. Other switch systems name the same three objects differently. Nothing here was applied to a switch, and the commands on the vendor page are not repeated as a recovery script.
Why it matters
Access switches fail loudly when a VLAN disappears: a floor loses its network. They fail quietly when the native VLAN changes: untagged frames, including traffic people forgot was untagged, join a different VLAN and nothing in the "VLAN is up" check notices. They fail worst when the change includes the management port. The operator who pushed the change can no longer reach the switch to push the previous one.
The gateway is a separate quiet failure. Hosts in the VLAN still talk to each other at layer 2. They cannot leave the VLAN, because the address they use as a gateway was on a switch virtual interface that the restore did not recreate, or that the restore tried to put in the wrong place. The bridge looks configured. The route does not exist.
A recovery plan that says "restore the VLAN configuration" has to say which of these three objects is in the file, which tool applies the file, and how the operator gets back in if the apply takes management with it.
What the bridge actually stores
In Cumulus Linux 5.15, VLAN-aware mode is the configuration model for a large layer 2 network with a single spanning-tree instance. Each physical member port carries the list of allowed VLANs and the port VLAN ID. Learning, filtering and forwarding are VLAN-aware. The page's example is a bridge with tagged VLANs 10 and 20 and untagged VLAN 1.
The same bridge can be written two ways on this page. NVUE sets the bridge domain, the VLAN list and the untagged VLAN, then applies the configuration. The interfaces file sets bridge-ports, bridge-vids, bridge-pvid and bridge-vlan-aware, and a network configuration reload applies it. Those are two expressions of one bridge, documented side by side. Our recommendation, not a statement that one overrides the other: a restore has to name which expression is the one you will apply. Applying a saved interfaces file and an NVUE candidate that were taken at different times is two restores. The page does not say what happens if you do both. Do not find out during the incident.
There is a default bridge in NVUE, br_default, with no ports assigned until you add them. A restore that resets to that default and stops is a bridge with no members. Ports are not in the VLANs until the membership is applied. "The bridge exists" is not "the ports are in it".
The native VLAN defaults to 1
The page says the primary VLAN identifier of the bridge defaults to 1. You do not have to set bridge-pvid. It then shows configurations that omit it and says they are identical to the configuration that sets it to 1. For the complete configurations illustrated on this page, omission selects the documented default rather than disabling untagged traffic. An incremental change that omits a setting may leave the existing setting unchanged; determine the apply tool’s merge/reset semantics.
That is the bad-push detail that a diff can miss. Someone removes bridge-pvid to tidy a file, or a backup tool drops a line it thinks is default, and untagged frames on that bridge are VLAN 1. If the design's native VLAN was anything else, the tidy file is a different network. The page says that even though the default does not change the configuration, setting it helps the next reader. Our recommendation: a recovery copy sets the native VLAN explicitly, including when it is 1, so a later restore cannot confuse "absent" with "VLAN 1 by default". The page does not require that. The silent default is why it is worth doing.
If bridge-vids or bridge-pvid is set on the bridge, every port in the bridge inherits it. Setting either value on a specific port overrides the bridge. A restore of the bridge without the port overrides moves every port to the bridge's list and the bridge's native VLAN. A restore of one port overrides the bridge for that port only. Partial files are how one access port ends up in a server VLAN, or how a trunk loses the VLAN that was only on the port.
The page also says not to bridge the management port, eth0, with any switch port. Its example is a bridge that contains eth0 and swp1: the bridge does not work correctly, and access to the management interface is disrupted. A VLAN restore that "adds the management port so we can reach it on the new VLAN" is the change that removes the way to undo the change. The recovery plan needs a path that is not a member of the bridge being restored. This article does not describe console cabling. It does say that a plan whose only path is eth0, and whose restore file puts eth0 in the bridge, has no path.
The gateway is not the bridge
The page's layer 3 section says to specify the attributes for each VLAN interface. If you are configuring the switch virtual interface for the native VLAN, you must declare the native VLAN and specify its IP address. Specifying the IP address in the bridge stanza itself returns an error.
So the gateway address lives on a VLAN interface, which the NVUE examples create as vlan10 or, when there is more than one bridge, as an interface of type svi with a VLAN and a base interface. It does not live on br_default. A restore that puts the gateway address on the bridge, because that is where some other system puts it, is the restore the page says returns an error. A restore that recreates the bridge and the port membership, and does not recreate the VLAN interface, brings back the broadcast domain and not the route out of it.
Hosts that can reach each other but not their gateway warrant an SVI check; missing addressing is one possible cause, alongside filtering, link state, VLAN tagging or routing-context errors. The check is whether the VLAN interface exists and has the address, not whether the bridge lists the VLAN. Both have to be in the recovery copy, as separate objects.
What you must not convert in place
The page says you cannot convert a traditional-mode bridge to or from a VLAN-aware bridge automatically. You must delete the original configuration and bring down all member switch ports before creating a new bridge. VLAN translation cannot be enabled on a VLAN-aware bridge at all. Only traditional mode bridges support it.
That is a destructive path, documented as a requirement, not as a convenience. Our recommendation: do not change bridge mode to recover from a bad push. Return to the mode the switch was already using, from a copy of that mode. A conversion during the incident means deleting the configuration and dropping member ports, which is a larger outage than the bad VLAN, and this article will not turn that requirement into steps. If the running mode is the wrong one for the design, that is a planned change with a tested copy and a window, not a recovery action.
The page also lists limits that a restore can trip without meaning to. You cannot use MLAG with more than one VLAN-aware bridge. You cannot put the same port in more than one. You cannot reuse the same VXLAN network identifiers across them, or use VLAN translation, or double-tagged interfaces, with multiple VLAN-aware bridges. A restore that creates a second bridge to "separate" a VLAN can break MLAG or refuse the port that is already in the first bridge. On Spectrum-2 and later, more than 1000 VLAN interfaces can exhaust the memory used for flow counters, and ACL application can then fail, with errors in switchd.log. A restore that creates a VLAN interface for every VLAN, because that seemed complete, can be the change that stops access lists from loading. The recovery copy should be the set of bridges and VLAN interfaces you actually run, not a generated complete matrix.
What to decide
The recovery copy contains, for each bridge: the member ports, the allowed VLAN list, the native VLAN written out even when it is 1, and any port that overrides the bridge. It contains, separately, each switch virtual interface: which VLAN, which bridge it sits on when there is more than one, and the address. It does not contain eth0 as a bridge member.
The plan names which tool applies that copy, NVUE or the interfaces file, and says the other tool is not applied from a different generation of the file in the same window.
The plan names the path used to reach the switch, and that path is not a port the restore might add to the bridge. If the apply fails halfway, the previous copy is the one already in hand, not a file still on the switch you can no longer reach.
The test after the apply is three checks, not one. Untagged frames on an access port are in the native VLAN you wrote down, not in VLAN 1 unless VLAN 1 is what you wrote down. A tagged VLAN that should be on a trunk is on that trunk, including ports that had an override. The gateway address answers on the VLAN interface, and a host in the VLAN can use it. A bridge that lists the VLAN is only the first of those.
Treat any required bridge-mode conversion as a separate disruptive, approved procedure with a tested return path. An active outage may require an emergency change window; the article does not prescribe that operation.
Risks and limits
This is Cumulus Linux 5.15, VLAN-aware bridge mode, as published by NVIDIA. Other releases in the same documentation set exist; this article did not open them. Cisco, Juniper and other switch systems use different configuration models for the same ideas. A port VLAN ID, a native VLAN and a switch virtual interface are the concepts. The setting names on this page are not theirs. IOS XE and Junos VLAN behaviour is outside this article’s source scope.
The page documents example commands. They were not run. ifreload and nv config apply change a live switch. This article does not tell you to run them.
"Do not bridge eth0" and "an address on the bridge stanza returns an error" and "you must delete the original bridge to convert" are the page's statements. "Write the native VLAN explicitly" and "do not convert mode during an incident" are recommendations on top of those statements.
Research and verification
Drafted with AI assistance on 11 November 2026 and independently source-reviewed on 13 November 2026. No equipment was configured, no article commands were executed and no lab behaviour is claimed. This is educational source research, not an approved production recovery procedure.
Sources
- NVIDIA, VLAN-aware Bridge Mode, Cumulus Linux 5.15. https://docs.nvidia.com/networking-ethernet-software/cumulus-linux-515/Layer-2/Ethernet-Bridging-VLANs/VLAN-aware-Bridge-Mode/ — VLAN-aware bridge, port VLAN ID and native VLAN, inheritance and port override, default PVID 1, management port
eth0, NVUE and/etc/network/interfaces, switch virtual interface addressing, error if the address is set on the bridge stanza, bridge conversion, multiple-bridge limits, VLAN interface scale on Spectrum-2 and later. Independently reopened 13 November 2026.
This article was originally published on .