Troubleshooting

Each section starts with what you see, then tells you what to do. Most fixes need the Homebridge log. To read it, open the Homebridge UI and click Logs in the side menu. The plugin’s lines start with [Home Connect Local]. In the examples below, the appliance is called Fridge. Your log uses your appliance’s name.

No Response

What you see: the Home app shows “No Response” on your appliance’s tiles. The Homebridge log has lines like these:

[Home Connect Local] Fridge: connection lost (...)
[Home Connect Local] Fridge: unreachable for 5 minutes; HomeKit shows No Response

“No Response” means the plugin has not been able to reach the appliance for 5 minutes in a row. During those 5 minutes, the tiles keep showing their last values. After that, the Home app shows “No Response” until the plugin connects again.

Wait first

What you see: before the 5 minutes are up, and between the other lines, the log repeats a line like this. The text after connect failed: says what went wrong. A line that keeps coming back ends with (repeated and a count.

[Home Connect Local] Fridge: connect failed: ...

These appliances save power on Wi-Fi by ignoring connections for minutes at a time. The Home Connect app can still show them as online while they do it. This is normal, and it fixes itself. The plugin keeps trying: first after 5 seconds, then waiting longer each time, up to 5 minutes between tries. It never gives up.

1. Wait 10 minutes.
2. Open the Home app again.

What you see afterwards: the tiles show values again, and the connect failed: lines stop.

If the tiles still say “No Response”, check the causes below.

The key was rejected

Each appliance has a key, which it uses to check that the plugin is allowed to connect. Pairing the appliance again in the Home Connect app, or resetting its network settings, gives it a new key. The key Homebridge has then stops working.

What you see: this error in the log:

[Home Connect Local] key rejected for Fridge: re-pair in the app if needed, re-download and re-import the profile

On the plugin’s settings page, Plugin status for that appliance starts with DISCONNECTED - key rejected for. The plugin writes this after the appliance rejects the key three times in a row. From then on, it tries that appliance only once every 30 minutes.

You may also see a line that contains stale pairing: re-pair the appliance in the Home Connect app, then re-download and re-import its profile. It means the same thing.

To fix it:

1. If the appliance is not working in the Home Connect app, pair it again in the app.
2. Download the appliance’s profile again, as in Step 2.
3. Import it, as in Step 3. The new profile replaces the old one.
4. Restart the plugin, as in Restart the plugin. The plugin then tries again straight away, instead of waiting 30 minutes.
5. Delete the zip from your computer.

The appliance answered in an unexpected way

What you see: this error in the log. Plugin status on the plugin’s settings page starts with DISCONNECTED - followed by the same text.

[Home Connect Local] Fridge answered with an unexpected text frame: its profile's connection type likely does not match the appliance, or something other than the appliance is answering on its port

The plugin writes this after the same thing happens three times in a row. From then on, it tries that appliance only once every 30 minutes.

To fix it:

1. If you set Host for this appliance, check that it is the appliance’s address. Your router’s list of connected devices shows it.
2. Download the appliance’s profile again, as in Step 2.
3. Import it, as in Step 3.
4. Restart the plugin, as in Restart the plugin.
5. Delete the zip from your computer.

What you see afterwards: the error does not come back, and Plugin status says CONNECTED.

The stored profile cannot be read

What you see: on the plugin’s settings page, under “Imported appliances”, a row says “Stored profile could not be read”, with the reason. This can happen after you restore only part of a backup.

To fix it, download that appliance’s profile again, as in Step 2, and import it, as in Step 3. Then restart the plugin.

One tile says No Response right after you add the appliance

A tile says “No Response” until the appliance has reported that feature once. A door sensor, for example, may need a moment after the plugin first connects. Wait a minute and look again.

How you know it worked

• The tiles in the Home app show values again.
• On the plugin’s settings page, Plugin status says CONNECTED.

Appliance not found

What you see: on the plugin’s settings page, On the network says not seen for the appliance. The Homebridge log has this line, and after 5 minutes a second one:

[Home Connect Local] no address for Fridge yet
[Home Connect Local] still no address for Fridge

The plugin finds appliances with mDNS. mDNS is the way devices on a home network announce themselves, so that others can find them without knowing their address. Each appliance announces itself on your network, and the plugin listens for it.

mDNS only reaches devices on the same network segment. A network segment is one part of your home network in which devices can hear each other’s announcements. Your Homebridge machine and your appliances must be on the same one. These setups split them up:

• An IoT VLAN. A VLAN is a separate network that your router keeps apart from the rest. Some people put smart devices on their own VLAN, often called an IoT VLAN. mDNS then cannot cross from that VLAN to Homebridge unless your router passes it along. A router feature that does this is called an mDNS reflector. Many routers have one. Look for mDNS in your router’s settings.
• Homebridge in a Docker container. See Docker and NAS.

If you cannot get mDNS to work, you do not need it. Tell the plugin the appliance’s address instead:

1. Find the appliance’s address. Open your router’s settings page or app, and look at its list of connected devices. The address looks like 192.0.2.50.
2. Give the appliance a fixed address, as in Give the appliance a fixed address. Otherwise the address can change later, and the plugin loses the appliance again.
3. Open the plugin’s settings page: on the Home Connect Local card, click the three dots, then click Plugin Config.
4. Under “Imported appliances”, note the appliance ID. It is on the line under the brand and model, before the ·.
5. Further down the page, find Appliance overrides and add an entry.
6. In Appliance ID (haId), type the appliance ID.
7. In Host, type the appliance’s address.
8. Click Save.
9. Restart the plugin, as in Restart the plugin.

With Host set, the plugin connects to that address and never waits for mDNS.

The Host address cannot be found

If you typed a name rather than an address in Host, the plugin has to look that name up. When the lookup fails, the log has a line like one of these:

[Home Connect Local] Fridge: cannot resolve the configured host fridge.home (...); using 192.0.2.50 found by mDNS instead
[Home Connect Local] no address for Fridge yet: cannot resolve the configured host fridge.home: ...

To fix it, open the plugin’s settings page, type the appliance’s IP address in Host, such as 192.0.2.50, click Save, and restart the plugin.

What you see afterwards: the cannot resolve the configured host lines stop.

How you know it worked

• On the plugin’s settings page, Plugin status says CONNECTED.
• The log no longer says still no address for your appliance.

If you set Host, On the network can still say not seen. That column only shows what the settings page found with mDNS. Plugin status is the one that counts.

Docker and NAS

Docker is a way of running a program, such as Homebridge, inside a sealed-off box called a container. It is common on NAS devices. A NAS is a storage box on your home network, which can often run programs too.

The way a container connects to your network decides whether the plugin can find your appliances.

• Bridge networking. This is Docker’s default. The container gets a private network inside the machine. mDNS announcements from your appliances do not get into it, so the plugin never finds them.
• Host networking. The container uses the machine’s own network connection, as if Homebridge were running directly on the machine. mDNS works.
• Macvlan networking. The container gets its own address on your home network, as if it were a separate device. mDNS works.

Use host networking

Your NAS’s container settings may call this “host” network mode. If you start Homebridge with Docker Compose, add this line to the Homebridge service:

network_mode: host

If you start it with docker run, add --network host.

When port 5353 is taken

A port is a numbered door on a device that one kind of connection uses. mDNS uses port 5353. Some NAS systems run their own mDNS service, which can take port 5353 for itself. A container with host networking then cannot use it.

What you see: this line in the Homebridge log. The text after the colon varies.

[Home Connect Local] mDNS discovery unavailable: ...

On one NAS, the Homebridge UI also kept restarting.

The plugin keeps working without mDNS. It connects to each appliance’s Host, or to the address where it last reached the appliance. You have two ways to fix this:

• Set Host for every appliance. Follow the steps in Appliance not found.
• Switch the container to macvlan networking. The container then has its own address, so port 5353 on it is free. On the NAS where this was tested, mDNS found both appliances with no Host set.

If the Homebridge UI keeps restarting, switch to macvlan networking.

Use macvlan networking

Your NAS’s container settings may offer macvlan as a network type. With Docker Compose, it looks like this. Replace eth0 with the name of your machine’s network connection, and the addresses with ones from your home network:

services:
  homebridge:
    # Keep your existing image, volumes and other settings.
    networks:
      homenet:
        ipv4_address: 192.0.2.20

networks:
  homenet:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.0.2.0/24
          gateway: 192.0.2.1

Here 192.0.2.20 is the address the container gets, 192.0.2.0/24 is your home network, and 192.0.2.1 is your router.

Macvlan has two side effects:

• The NAS itself cannot reach the container’s address. Other devices on your network can. Open the Homebridge UI from another computer or a phone, at the container’s new address, such as http://192.0.2.20:8581.
• Your router does not know the container’s address is taken. It might give the same address to another device later. In your router’s settings, reserve the address, or pick one outside the range your router hands out. Give the appliance a fixed address explains reservations.

How you know it worked

• The log no longer says mDNS discovery unavailable.
• On the plugin’s settings page, On the network shows an address for each appliance.
• Plugin status says CONNECTED.

If you set Host instead of changing the network, On the network can still say not seen. Plugin status is the one that counts.

Give the appliance a fixed address

Your router hands out addresses to the devices on your network. This is called DHCP. By default, a device can get a different address from time to time, for example after the router restarts. If you set Host for an appliance, or if mDNS does not work in your setup, a changed address means the plugin cannot find the appliance.

A DHCP reservation fixes this. It tells your router to give one device the same address every time. Every router does this differently, so this is the general idea:

1. Open your router’s settings page or app.
2. Find the list of connected devices, or the DHCP settings.
3. Find the appliance. The plugin’s settings page shows its current address under On the network, which helps you pick it out.
4. Choose to reserve that address for it. Routers call this a reservation, a static lease or a fixed IP.
5. Save.

If you use Host, set it to the reserved address. Follow the steps in Appliance not found.

How you know it worked

• Your router lists the appliance with the reserved address.
• After your router restarts, the appliance has the same address, and Plugin status on the plugin’s settings page says CONNECTED.

Other messages

An appliance could not be set up

What you see: this error in the log, with the appliance’s ID, or the Accessory name you set, at the start. The text after the colon says why.

[Home Connect Local] BOSCH-KSN36VICG-000000000000 could not be set up, so it is unavailable until the next restart: ...

Plugin status for that appliance starts with DISCONNECTED - followed by the reason. Its tiles in the Home app keep their old values and do not change.

To fix it, restart the plugin, as in Restart the plugin. If the error comes back after the restart, open an issue on GitHub and paste the line. Remove anything that identifies your appliance first, as described in Before you share a log.

What you see afterwards: the error does not come back, and Plugin status says CONNECTED.

Plugin status says never connected

What you see: on the plugin’s settings page, Plugin status for an appliance says never connected. The plugin has not yet connected to that appliance.

To fix it:

1. Restart the plugin, as in Restart the plugin. The plugin only starts using a new profile after a restart.
2. If it still says never connected after a few minutes, check that you have not turned Enabled off for that appliance under Appliance overrides. If you have, the log says Fridge is disabled in config.json; skipping it.
3. If neither applies, see Appliance not found and No Response.

What you see afterwards: Plugin status says CONNECTED. The appliance saves power by ignoring connections for minutes at a time, so give it a few minutes.

How you know it worked

On the plugin’s settings page, Plugin status says CONNECTED for every appliance.

Debug logging

Debug logging makes Homebridge write more detail to its log. Use it to find out why a tile is missing, or to collect a log for a bug report. The plugin has no debug setting of its own. It uses Homebridge’s debug mode, which is the same as starting Homebridge with -D.

Turn it on

If you followed Step 1, the plugin runs in a child bridge:

1. In the Homebridge UI, click Plugins in the side menu.
2. On the Home Connect Local card, click the three dots, then click Child Bridge Config.
3. Turn on Debug Mode.
4. Click Save.
5. On the card, click the three dots, then click Restart Child Bridge.

If you turned the child bridge off:

1. In the Homebridge UI, click Settings in the side menu.
2. In the Startup & Environment section, turn on Homebridge Debug Mode.
3. In the side menu, click Power Options, then click Restart Homebridge.

What to look for

In the side menu, click Logs. These are the useful lines:

• Features without a tile. Each line contains unmapped:, names a feature the appliance has, and says why it has no tile:

  [Home Connect Local] Fridge: unmapped: Refrigeration.Common.Status.Compartment1.TemperatureCelsius (no HomeKit equivalent in v1)

• Connection steps. Each line shows the plugin moving from one step to the next, such as from CONNECTING to CONNECTED, or to BACKOFF while it waits to try again:

  [Home Connect Local] Fridge: connecting to 192.0.2.50 (from mdns)
  [Home Connect Local] Fridge: CONNECTING → AWAIT_INIT

  from mdns means the plugin found the address with mDNS. from config means it came from Host, and from state means it is the address where the plugin last reached the appliance.

Before you share a log

A log can identify your appliances and your network. Copy only the lines that start with [Home Connect Local]. Then replace each of these with a made-up value before you post the log anywhere:

• appliance IDs, such as BOSCH-KSN36VICG-000000000000
• IP addresses, such as 192.0.2.50
• serial numbers
• MAC addresses, the network hardware IDs of your devices, such as 00-00-5E-00-53-01
• the names of profile zips, because they contain the appliance’s MAC address

Never attach a profile zip, or any file from the homeconnect-local folder in Homebridge’s storage folder. Those files hold your appliance keys.

When you are done, turn debug mode off again the same way you turned it on.

How you know it worked

After the restart, the log has lines from the plugin that it does not write without debug mode, such as one that starts with your appliance’s name followed by compartments:.