home-assistant / home-assistant/core

Matter: bridged endpoints under a nested Aggregator device lose their via_device link

Open
#182,091 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

by-code-owner integration: matter
Dominant language
Python
Stars
90.8k
Forks
38.7k
Avg merge
1d 2h
Merged PRs (30d)
597

Description

The problem

When a Matter bridge exposes a bridged endpoint that is itself an Aggregator device type (i.e. a bridge nested inside the main bridge, with its own child endpoints), Home Assistant attaches that nested Aggregator's children directly to the top-level bridge device instead of nesting them under the Aggregator endpoint they actually belong to. In the device registry they show up as siblings of the nested Aggregator device rather than its children.
Everything lands flat under the bridge, as if the nested Aggregator were just another top-level accessory.

Reproduced with Matterbridge's built-in demo device set (matterbridge --demo-devices --profile Demo), which includes exactly this
topology: an Aggregator (0x0e) bridged endpoint carrying BridgedDeviceBasicInformation, with four OnOffPlugInUnit children under it
that do not carry their own BridgedNode device type.

Matterbridge log excerpt showing the topology:

Matterbridge.Matterbridge.Aggregator ready endpoint#: 1102 type: Aggregator (0x0e, rev 2)
  behaviors: ✓descriptor ✓matterbridge ✓powerSource ✓fixedLabel ✓bridgedDeviceBasicInformation
Matterbridge.Matterbridge.Aggregator.Plug1 ready endpoint#: 11021 type: OnOffPlugInUnit
  behaviors: ✓descriptor 💤matterbridge ✓identify ✓groups ✓scenesManagement ✓onOff
(same for Plug2/3/4, endpoints 11022–11024)

Likely root cause (two contributing pieces):

  1. python-matter-server's client model
    (matter_server/client/models/node.py, in MatterNode.update()) skips any
    endpoint that carries the Aggregator device type when building the
    composed-device parent/child map:

    if Aggregator in endpoint.device_types:
        continue  # ignore Bridge endpoint (its partsList indicates its own bridged children)
    

    This is correct for the node's top-level bridge aggregator, but it also
    skips a nested Aggregator endpoint, so its PartsList children are never
    recorded as belonging to it.

  2. In homeassistant/components/matter/adapter.py, _create_device_registry
    computes via_device_id for any bridged endpoint as
    endpoint.node.endpoints[0] — hardcoded to the node's root endpoint,
    regardless of the endpoint's actual immediate bridge/aggregator parent:

    if endpoint.is_bridged_device and endpoint.node.endpoints[0] != endpoint:
        bridge_device_id = get_device_id(server_info, endpoint.node.endpoints[0])
        via_device_id = ...
    

Combined, a nested Aggregator's children end up attached directly to the node's root device instead of to the Aggregator endpoint that is their real parent.

This is fully deterministic (not a race), reproducible on every startup with the demo device set.

What version of Home Assistant Core has the issue?

core-2026.9.2 (also present on latest dev, unchanged since 2026.9.0)

What was the last working version of Home Assistant Core?

Unknown

What type of installation are you running?

Home Assistant OS

Integration causing the issue

matter

Link to integration documentation on our website

https://www.home-assistant.io/integrations/matter/

Diagnostics information

matter-nested-aggregator-diagnostics.json

Example YAML snippet

Anything in the logs that might be useful for us?

Additional information

Reported by a Matterbridge maintainer who observed bridged endpoints landing
flat under the root device instead of under their aggregator parent. Repro
steps:

  1. npm i -g matterbridge (or use an existing install)
  2. matterbridge --demo-devices --profile Demo
  3. Pair it with Home Assistant's Matter integration
  4. In Settings → Devices, check the "Aggregator" device's children (Plug1–4):
    they show up as top-level devices under the bridge, not nested under
    "Aggregator".

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with MatterNode.update() in matter_server/client/models/node.py and _create_device_registry in homeassistant/components/matter/adapter.py, then reproduce the topology with Matterbridge's --demo-devices --profile Demo command. Done means the four nested Plug endpoints appear under the Aggregator device rather than as siblings under the root bridge.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, embedded-iot
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.