Advanced bridge settings and feature flags
Work through the Stable 2.0.55 BridgeConfig field by field, together with the form and the JSON validation, and put identity, session, sync, cover, fan, vacuum and the Alexa workaround into the right controller context.
A feature flag is a precise workaround, not a switch to turn everything on
Bridge settings carry three kinds of responsibility at once: the filter that decides the candidate entities, the runtime parameters that pin the Matter node, and the workarounds you turn on for one controller's behavior. These fields can change endpoint identity, the cluster composition, the sync frequency or the meaning of a control command. Get a working baseline bridge first, then change one related option at a time.
This chapter follows the Stable 2.0.55 schema and bridge-data.ts. A feature "being in the Stable release" does not mean its maturity is production; serverMode is in the Stable channel, yet a node with more than one device is still explicitly experimental. Controller support is a third fact again: the Alexa-only brightness workaround, for example, breaks certain Siri operations in Apple Home, so you cannot turn it on for a multi-fabric bridge just because it "looks helpful".
serialNumberSuffix, uniqueIdSuffix and some per-entity identity overrides make a controller treat a device as new, or confuse the cache from an earlier commissioning. Back up the persisted data, record the original values and the controller impact, then plan the restart and the rediscovery. Do not make a suffix change your first troubleshooting step.Every top-level BridgeConfig field
| Field | Schema / scope | Purpose and how far you may change it |
|---|---|---|
name | Required string, 1–32 characters | The bridge name in the interface. In Server Mode the first entity also drives the node identity and type, so do not confuse the two. |
port | Required number, minimum 1 | The port the bridge listens on. The editor also validates that it does not duplicate another bridge; the create flow can let the backend find the next free port, but an existing BridgeConfig has to carry a value. |
filter | Required object | Holds the required include and exclude arrays plus the optional includeMode. For every matcher, see Chapter 5. |
featureFlags | Optional object | Listed one by one through the rest of this chapter. Most booleans default to false; there are exceptions, and leaving a flag out carries a meaning of its own. |
countryCode | Optional string, 2–3 characters | The schema describes it as an ISO 3166-1 alpha-2 country code, needed only when commissioning fails for a missing country code. Use the documentation placeholder <COUNTRY_CODE>; do not copy values from a live system. |
icon | Optional enum | For display in the interface; the choices are light, switch, climate, cover, fan, lock, sensor, media_player, vacuum, remote, humidifier, speaker, garage, door, window, motion, battery, power, camera, default. It does not change the Matter device type. |
priority | 1–999, default 100 | Startup precedence; the lower the number, the earlier it starts. It is an order, not a controller priority. |
serialNumberSuffix | Optional, up to 16 characters | Appended to the serial number of every entity on this bridge, which can make a controller bypass an old cache; the devices may be recognized as new ones. |
uniqueIdSuffix | Optional, up to 16 characters | Mixed into the uniqueId of every bridged device in standard bridge mode, and takes effect after a restart. Server Mode falls outside the scope its comment names. |
sessionMaxAgeHours | 0–168 hours | Rebuilds an over-age Matter session and makes it re-subscribe; 0 turns it off. Server Mode rotates every 4 hours by default, and a standard bridge only does it when you set this field. |
The schema sets additionalProperties: false on the top level and on the filter, so a misspelled field is not a comment you can ignore — it is a validation error. The feature flag schema does not spell out additionalProperties false, but you still should not add keys the source never defines. The form hands the icon to a separate Bridge Icon component, so the icon is kept when you switch between the form and JSON.
Visibility, composition, auto-sync and naming flags
| flag | Default / maturity | Exact behavior |
|---|---|---|
includeHiddenEntities | false; mature | Lets a Home Assistant hidden entity that the filter matches into the bridge. It does not undo a disabled setting in Entity Mapping. |
serverMode | false; experimental in Stable | Exposes entities as standalone Matter devices instead of bridged devices. Each node carries at most 10 devices; the first is the primary and decides the node name and type. More than one device is still experimental. |
autoBatteryMapping | false; mature | Attaches the battery sensor of the same HA device to the primary entity, so it does not turn into a separate device in the controller. |
autoHumidityMapping | true; mature | Composes humidity and temperature from the same HA device automatically. The code tests for "not explicitly false", so leaving it out also enables it. |
autoPressureMapping | true; mature | Composes pressure and temperature from the same HA device automatically; leaving it out also counts as enabled. |
autoComposedDevices | false; mature | The master toggle for composed devices; it enables the battery, humidity, pressure, power and energy automatic mappings together. More clusters also means more data to sync. |
autoForceSync | false; a mature workaround | Every 90 seconds it compares and pushes the state of every device, for the case where Google Home or Alexa loses a subscription. The health check does not depend on this flag. |
productNameFromNodeLabel | false; mature | Reports the resolved nodeLabel as the productName, for controllers that use productName as the device name; a per-entity customProductName wins. |
preferEntityRegistryName | false; a mature workaround | Changes the nodeLabel order to customName → registry name → registry original_name → friendly_name → entity_id, to handle the HA 2026.4 change to the friendly_name prefix. Matter has no alias; only one name can be reported. |
useHaRegistrySerial | false; mature | Where there is no per-entity custom serial, uses the HA device registry serial_number; only when that is missing too does it fall back to the entity-ID-based hash. Changing a serial after commissioning can confuse a controller. |
batteryEntity, humidityEntity and the rest are links you state yourself. You cannot tell the two apart by guessing from the controller screen — cross-check the mapping information on the Devices card.Cover, fan, vacuum and Alexa behavior
| flag | Effect | Controller limits |
|---|---|---|
coverDoNotInvertPercentage | Skips the percentage inversion of Matter's standard direction so the number matches HA; the schema says plainly that this does not conform to Matter. | Use it only once you have confirmed you need those value semantics; do not confuse it with reversing the commands. |
coverUseHomeAssistantPercentage | Shows the HA percentage while the Open and Close commands stay correct; a high percentage in HA means more open, and Alexa often reads it as more closed. | The schema marks it Alexa-friendly, but the difference in meaning is still there. |
coverSwapOpenClose | Swaps the open and close commands and inverts the position report. | Use it only when a spoken "close" opens the cover instead; the per-entity override of the same name can handle a single cover first. |
coverSliderDebounceMs | 0 keeps the built-in two stages of 400/150 ms; above 0 it becomes a single wait window, in the range 0–5000 ms. | For Apple Home sending a continuous stream of slider updates; a per-entity value for one cover wins. |
fanSliderDebounceMs | Waits for the last fan-speed write before sending it to HA, in the range 0–10000 ms; 0 sends every one immediately. | Suits devices that beep on every frame over IR or UART; a per-entity value wins, and the Entity Mapping UI caps it at 5000 ms. |
vacuumOnOff | Adds an OnOff cluster for an RVC, and has no schema default. | In v2.0.55 the actual registry adds it only on an explicit true, in both bridge and Server Mode; leaving it out and setting false both leave it off. The bridge-data.ts comment and the schema still describe Server Mode adding it automatically when it is unset, which contradicts the running code, so go by the running code. Set true where Alexa needs it; a non-standard cluster can affect Apple and Google. |
alexaPreserveBrightnessOnTurnOn | Ignores a full-brightness command that arrives within 200 ms of the same light turning on, so the light does not go back to 100% after an Alexa subscription renewal. | Only on an Alexa-only bridge; it breaks the room-level "set to 100%" Siri command in Apple Home. |
vacuumIncludeUnnamedRooms | Present in the type declaration in bridge-data.ts. | The v2.0.55 schema has no such field, and nothing in the packages at the exact commit reads it at runtime; you therefore cannot claim it is settable in the UI or has a verifiable effect. Do not rely on it. |
Controller profiles are a suggested combination at create time, not a live compatibility guarantee: the Apple profile turns on composed, battery, humidity and pressure; Google adds autoForceSync; the Alexa profile turns on autoForceSync, battery, humidity and pressure plus the HA cover percentage; Multi-Controller keeps the standard cover behavior. Once a profile is applied it is still an ordinary BridgeConfig, and you have to verify it against your actual controller and device types.
Stable identity, session recovery and the watchdog
| Setting | Trigger | Handles / does not handle |
|---|---|---|
stableIdentity | Once enabled it anchors the endpoint id, uniqueId and serialNumber to the HA entity registry unique_id. | When an HA entity_id is renamed, the controller can keep its groups, names and automations. Identity records are seeded from the start, so turning it on later should not re-add existing devices. It does not replace a data backup. |
fastSessionRecovery | A controller loses all of its subscriptions. | Clears the dead session and re-announces after 5 seconds instead of 60; it shortens the Google offline window, and cannot stop a controller from refusing a subscription. |
wedgeWatchdog | The subscription is still alive, but no inbound Interaction Model request has arrived from the controller for about 45 minutes. | Rotates a single session that looks wedged early, aimed at Apple Home showing Updating. The cost of a false positive is a transparent CASE re-establishment; it does not mean every network fault can be repaired. |
sessionMaxAgeHours | A session is older than the age you set. | A blind rotation by age that prompts a re-subscription; 0 turns it off. It is a top-level field, not a feature flag. |
autoForceSync | A 90-second cycle. | It pushes state, which is not the same as clearing a session. Turned on alongside composed devices, it adds traffic. |
These mechanisms work at different layers: identity gives device continuity across an HA rename; session rotation, fast recovery and the watchdog deal with the Matter connection and its subscriptions; autoForceSync deals with pushing state. Do not turn them all on at once and then try to work out which one helped. A home bridge that serves several controllers especially should start from neutral settings, with controller-specific workarounds split onto their own bridge.
Switch safely between raw JSON and the field editor
Back up the current configuration
Export from the existing bridge first, or record the non-secret settings some safe way, and confirm the persisted data has a backup you can restore from. Do not paste identifying data from a live environment into a document or a ticket.
Open Edit and switch to JSON
On the bridge edit page, press the editor toggle in the top right to move from the Fields Editor to the JSON Editor. Keep the required
name,port,filter.includeandfilter.exclude.Add only keys the schema defines
Check the structure with documentation placeholders, for example
"countryCode": "<COUNTRY_CODE>". Write booleans as true/false, and the debounce and session age as numbers; do not put a number inside quotes.Read the live validation output
Fix errors in the JSON syntax, the required fields, the enums, the minimum and maximum values and additional properties. If another bridge already uses the port, the custom validation blocks the save as well.
Switch back to the form and cross-check
Confirm the fields still show the values you expect. Check in particular that
vacuumOnOffis explicitly true only where Alexa needs it, and that the icon has been kept by its own separate control.Save one set of changes at a time
After you press Save, verify at the layer that flag belongs to: for identity, check continuity across a rename; for session, check Health; for cover, fan and vacuum, check a single test device. An identity suffix that only applies after a restart needs a downtime window arranged first.
Pick the smallest setting that matches the symptom
| Confirmed symptom | Assess first | Do not do at the same time |
|---|---|---|
| The controller rebuilds the devices after an entity_id change in HA | stableIdentity | Changing the serial or unique suffix at the same time; you then cannot tell where the identity change came from. |
| Google goes offline after cancelling a subscription | fastSessionRecovery, then assess autoForceSync if you need to | Mistaking an unreachable network for a subscription problem. |
| An Apple tile shows Updating for a long time and the subscription is still there | wedgeWatchdog, or plan a session age rotation | Going straight to a reset or a fresh commissioning; look at Health and the redacted logs first. |
| Brightness jumps to full after Alexa turns a light on | alexaPreserveBrightnessOnTurnOn on an Alexa-only bridge | Turning it on for a bridge that also serves Apple Home. |
| Voice open and close are reversed on a cover | coverSwapOpenClose, per-entity first for a single device | Changing the percentage flags first; command direction and percentage display are different things. |
| Dragging a fan or cover slider produces repeated commands to the entity | The matching debounce, tested first as a single-entity override | Treating the update throttle as an inbound command debounce. |
Where one bridge serves Apple, Google and Alexa at once, start from the neutral Multi-Controller semantics; split the bridge when you need workarounds that exclude each other, because one endpoint cannot use the standard cover semantics and a controller-specific inversion at the same time, and cannot both ignore Alexa's full-brightness sequence and keep the same sequence for Apple.
Troubleshooting advanced settings, and safe fallback points
The Save button is disabled
Switch back to the form and read the validation: the name length, a duplicate port, the required filter arrays, an enum, the debounce or session range and an unknown top-level key can each make the configuration invalid. Do not bypass the schema and edit storage directly.
A vacuum does not appear after Alexa commissioning
Check that
vacuumOnOffis explicitly true; in v2.0.55 the running code never adds it automatically for an omitted field, in either bridge or Server Mode. If the same bridge also serves Apple or Google, assess a split first rather than sacrificing the other controllers.Apple room brightness voice commands stop working
Check whether
alexaPreserveBrightnessOnTurnOnis on for a bridge that includes Apple. Turn it off and return to controller-neutral settings; do not change the light's type or identity at the same time.Duplicate devices appear after a suffix change
That is exactly what minting a fresh identity can produce. Restore the original suffix, confirm the original configuration from the backup, then work through your controller's safe operations process. Do not keep changing the suffix and mint yet more identities.
Auto Force Sync is on and it still shows offline
It only pushes state on a schedule. Look at the session and subscription in Health and at the network status; where a subscription was cancelled, assess fast recovery; where it looks wedged, assess the watchdog for that controller type.
A global value does not suit one cover or fan
Clear the bridge-level workaround or keep the neutral value, and set a per-entity
coverSwapOpenCloseor cover and fan debounce in Entity Mapping instead; a per-entity setting wins and affects less.
Bridge settings FAQ
Is Server Mode in the Stable channel a production-grade feature?
Is vacuumOnOff: false the same as leaving it out?
Does Auto Composed Devices cover every manual linked field?
Do you still have to change a suffix once stable identity is on?
Why do the docs list vacuumIncludeUnnamedRooms when the form has no such field?
Stable 2.0.55 pinned-version sources
- bridge-data.ts: BridgeConfig and every feature flag declaration
- bridge-config-schema.ts: editor fields, defaults and validation ranges
- controller-profiles.ts: the Apple, Google, Alexa and Multi-Controller recommended values
- BridgeConfigEditor.tsx: form and JSON, warnings and port validation
- bridge-registry.ts: automatic mapping, hidden entities and vacuum behavior
- The official v2.0.55 release