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.

• Home
• Debug Mode
• Validate config.json Format
• Understanding Where Your Files Are (macOS)
• Reset Pairing/Accessories
• Home Can't Connect To Accessory
• Examine Logs For Errors
• Error - Not A Valid Username
• Error - EADDRINUSE
• Best HomeKit App

• Home
• NPM Registry Issues
• Eero Routers
• Multiple Instances Of Homebridge Found Installed
• Unable To Find Homebridge Installation
• Error - update-node - Your Version Of Linux Does Not Meet The GLIBC Version

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

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

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:

• How To Fix Node.js Install Issues On Linux
• How To Fix Node.js Install Issues On macOS

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

sudo npm install -g --unsafe-perm homebridge

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.

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.