Skip to content

Troubleshooting

Jump to bottom
Ben edited this page Nov 9, 2024 · 31 revisions

There does not yet exist a way to do systematic troubleshooting. However, we encourage you to isolate your issues into the smallest parts possible and come up with a way to test each issue.

For example, if you have permissions trouble or errors installing npm, solve that problem first by using any error messages to search for solutions. Once that problem is solved, move on to the next problem.

Homebridge Troubleshooting

Homebridge UI Troubleshooting (on this page)

Errors During Installation

Make sure you installed the package with sudo and used the --unsafe-perm flag. Most installation errors can be fixed by removing the Homebridge UI and reinstalling:

# cleanup
sudo npm uninstall -g homebridge-config-ui-x

# reinstall
sudo npm install -g --unsafe-perm homebridge-config-ui-x

Make sure you are running supported versions of node and npm.

Home App Says Accessory Already Added

To fix this, Reset Homebridge.

My iOS App Can't Find Homebridge

Try the following:

  1. Swap between the Bonjour HAP and Ciao mDNS Advertiser options. See the wiki for more details.
  2. iOS DNS cache has gone stale or gotten misconfigured. To fix this, turn airplane mode on and back off to flush the DNS cache.

NPM Registry Issues

Error messages include:

  • Failed to check registry.npmjs.org for updates ...
  • Failed to search the npm registry ...

This is not an issue with Homebridge Config UI X in most cases.

Look for these keywords in the error message to help troubleshoot the issue:

  • getaddrinfo - your DNS resolver could not resolve registry.npmjs.org. Check your internet connection and DNS settings.
  • ETIMEDOUT or Timeout - the request took too long, the npm registry may be down, slow, or you may have internet issues, check https://status.npmjs.org/. Other potential sources can be broken IPv6 implementations, disabling IPv6 has been reported to resolve.
  • Request failed with status code 503 - the npm registry is down, check https://status.npmjs.org/.
  • certificate has expired - check the date/time on your server is correct
  • certificate is not yet valid - check the date/time on your server is correct

Eero Routers

If you are using an Eero brand router, see How To Fix Eero Router Internet and DNS Connectivity Issues.

Multiple Instances Of Homebridge Found Installed

This message will be displayed when the UI has found multiple copies of Homebridge installed in different locations. This is usually caused by multiple versions of Node.js installed using different methods.

See the following guides to fix your setup:

Unable To Find Homebridge Installation

This message is displayed when the UI cannot find the Homebridge package. Try installing it:

sudo npm install -g --unsafe-perm homebridge

Error - update-node - Your Version Of Linux Does Not Meet The GLIBC Version

This message indicates that your operating system does not support the requested version of NodeJS. To resolve this and be able to install the updated NodeJS, you will need to update your operating system to a more recent version.

To Install Node.js: Needed gclib Version
18 >=2.28
20 >=2.29

An operating system update will require rebuilding your setup, but with some simple steps, you will not lose your existing configuration. Creating a Homebridge Archive/Backup and restoring it after the Operating System upgrade will keep your existing configuration and HomeKit settings. Also doing the Operating System upgrade on a new SD card will allow you to keep your existing card as an additional backup.

It is also recommended to shut down your Apple Home Hubs during the update and turn them on again after the update is complete.

Installation

Homebridge Help

Homebridge UI Help

Versioning

Plugins

Developers

Clone this wiki locally