Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Frequently Asked Questions

I’ve got connectivity issues, what can I do?

Please follow the troubleshooting guide.

I’d like to connect my bridge to multiple assistants

Please follow the multi-fabric guide.

I’m running HAMH as a docker image and want to access it via a reverse proxy

Please follow the reverse proxy guide.

Changes on names and labels in Home Assistant have no effect in HAMH

When performing changes on entities, like adding or removing a label or renaming your entity, you need to reload the affected bridge for the changes to take effect. This happens automatically every 30 seconds, but you can enforce it by editing the bridge (even without making changes), or when restarting the whole addon.

I added a label to my entities, but HAMH won’t find any device

If you just can’t get it working with your labels, try to delete your label and re-create it.

My Vacuum does not appear in the Apple Home App

Ensure that all home hubs in the Apple Home app are updated to iOS/tvOS/AudioOS 18.4 or later – if any home hub is below 18.4, the vacuum device will not show up. To resolve this:

  1. Check for updates

    • iPhone / iPad:
      Settings > General > Software Update

    • HomePod:
      Open the Home app → Home Settings → Software Update

    • Apple TV:
      Settings > System > Software Updates

  2. Install any pending updates, then restart each hub.

  3. Relaunch the Home app and confirm the vacuum now appears under your accessories.

How do I access the Health Dashboard?

Click the heart icon (❤️) in the top navigation bar of the web UI, or navigate directly to /health.

My bridge keeps failing and restarting

The automatic recovery feature will restart failed bridges. If a bridge keeps failing:

  1. Check the logs for specific error messages

  2. Reduce the number of devices in the bridge

  3. Verify all entities in the bridge are valid

  4. Try factory resetting the bridge

How do I use the Bridge Wizard?

  1. Go to the Bridges page

  2. Click the Wizard button

  3. Follow the guided steps to create bridges

  4. Ports are automatically assigned starting from 5540

What sensors are supported?

Currently supported sensor types:

See Temperature & Humidity Sensor for details on combining temperature, humidity, pressure, and battery into a single device.

The app keeps crashing or restarting on my HA Yellow / Raspberry Pi

Low-resource devices (1–2 GB RAM) can run out of memory when running many bridges or devices. Since v2.0.17, HAMH limits the Node.js heap to 512 MB to prevent uncontrolled OOM kills. If crashes persist:

  1. Reduce the number of devices per bridge

  2. Split large bridges into smaller ones (e.g. per room)

  3. Consider using a device with more RAM

See #141 for details.

Alexa loses connection after a few hours

This was caused by “dead sessions” — Alexa goes offline but the bridge keeps the old session alive, blocking new subscriptions. Since v2.0.17, the bridge detects and force-closes dead sessions automatically. If you still experience this:

  1. Update to the latest version

  2. Remove and re-pair the bridge in the Alexa app

  3. Check your network for multicast/mDNS issues (see Connectivity Issues)

See #105 for details.

My cover / blinds open and close commands are inverted

Matter and Home Assistant use different conventions for cover position percentages. Use the bridge feature flags to fix this:

Configure these in your Bridge Settings → Feature Flags. See #107, #109.

Battery shows as a separate device instead of being part of the sensor

HAMH has Auto Battery Mapping enabled by default. It automatically finds battery sensors on the same HA device and combines them with the primary sensor (temperature, climate, fan, vacuum). If it still shows separately:

  1. Check that the battery entity belongs to the same HA device as the primary entity

  2. Make sure autoBatteryMapping is enabled in your Bridge Settings → Feature Flags

  3. Alternatively, use Entity Mapping to manually set batteryEntity on the primary sensor

See #99.

My thermostat doesn’t work correctly in auto mode

Matter’s “Auto” mode means the thermostat automatically switches between heating and cooling based on temperature. This maps to HA’s heat_cool mode, not auto. Since v2.0.17:

This prevents Alexa from rejecting commands on single-capability thermostats. See #143, #136.

My water heater / kettle max temperature is capped at 50°C

Previously the default Matter thermostat limits capped water heaters at 50°C. Since v2.0.17, HAMH reads the actual min_temp and max_temp from your HA entity and passes them correctly. Update to the latest version to fix this.

See #145, #97.

Matter hub appears multiple times in Alexa / duplicate connections

This can happen when a bridge is factory-reset or re-created while still paired in Alexa. To fix:

  1. Remove all duplicate entries from the Alexa app

  2. Factory reset the bridge in HAMH (Bridge Settings → Factory Reset)

  3. Re-pair the bridge in Alexa

See #152.

My binary sensor shows “Open/Closed” instead of “On/Off” (running, plug, power)

Binary sensors with device_class running, plug, power, battery_charging, or light are now mapped to OnOffSensor (On/Off) instead of ContactSensor (Open/Closed). This was fixed in v2.0.17.

If you’re on an older version, update to get the correct mapping. See #154.

My devices are not assigned to the correct rooms

HAMH sends your Home Assistant area names to Matter controllers using the FixedLabel cluster (label: "room", value: "<area name>"). However, no major controller (Google Home, Apple Home, Alexa) currently reads this label for automatic room assignment. You need to assign rooms manually in each controller app during or after pairing.

The FixedLabel data is kept in the bridge for future controller support. The room name is limited to 16 characters per the Matter spec — longer HA area names are truncated automatically.

How do I control Media Player playback?

Media players now support Play, Pause, Stop, Next Track, and Previous Track controls through Matter. However, not all controllers support these features yet. Volume control is also available.

What’s the difference between Stable and Alpha?

See the Alpha Features Guide for details on alpha features.

How do I report an Alpha bug?

When reporting Alpha issues, include:

My thermostat doesn’t turn on when I set the temperature

Since v2.1.0-alpha, thermostats support auto-resume — when off and you set a temperature (even the same one), it automatically turns on. This works with all voice assistants.

If not working:

Vacuum shows “Paused” instead of “Docked”

Fixed in v2.1.0-alpha. Previously some vacuums (Ecovacs, some Roborock) reported idle while docked, showing as “Paused”. Now correctly shows “Docked” when charging.

Too many “No battery entity found” log messages

Fixed in v2.1.0-alpha. Battery sensor auto-mapping now uses caching and reduced log levels (debug only). Previously every entity without battery logged a warning.

Bridge runs out of memory after several days

Fixed in v2.1.0-alpha. Endpoint disposal was improved in BridgeEndpointManager and ServerModeEndpointManager. Previously endpoints weren’t cleaned up during restarts, causing memory leaks.

How do I use the Dashboard landing page?

Since v2.1.0-alpha, the app opens with a Dashboard showing:

Refreshes every 15 seconds.

What is “Auto Composed Devices”?

Auto Composed Devices (autoComposedDevices feature flag, since v2.0.20) combines related entities from the same HA device into one Matter endpoint:

Enable in Bridge Settings → Feature Flags.

Devices
Temperature, Humidity & Pressure Sensor
Developer Documentation
Developer Documentation