Troubleshooting

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
• Errors During Installation
• NPM Install-Script Approval
• The Homebridge UI Will Not Load
• Home App Says Accessory Already Added
• My iOS App Can't Find Homebridge
• homebridge.local Stops Working After Enabling Matter
• 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

Make sure you installed the package with sudo. 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 --allow-scripts=homebridge-config-ui-x,@homebridge/node-pty-prebuilt-multiarch,macos-temperature-sensor,osx-temperature-sensor homebridge-config-ui-x

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

Newer npm versions require the caller to explicitly approve installation scripts for globally installed packages. A globally installed package cannot approve its own dependencies through its allowScripts configuration. This affects native Homebridge UI installations on Linux, macOS, and Windows. See issue #3021.

If installation reports npm warn install-scripts with packages not covered by allowScripts, required native installation scripts may have been skipped even if npm reports that packages were added successfully. With --strict-allow-scripts, npm reports ESTRICTALLOWSCRIPTS instead.

For an installation managed through global npm commands, reinstall Homebridge and the UI with explicit script approval:

sudo npm install -g --allow-scripts=homebridge-config-ui-x,@homebridge/node-pty-prebuilt-multiarch,macos-temperature-sensor,osx-temperature-sensor homebridge homebridge-config-ui-x

On Windows, run the same command without sudo from an administrator Node.js command prompt.

After installation completes successfully, restart an existing service with hb-service restart (use sudo on Linux). For a new installation, continue with the service setup step in your platform's installation guide.

The approval list covers the Homebridge UI and its native dependencies, including the macOS temperature sensors. It does not approve the optional @scarf/scarf reporting script, so npm may still warn about that script. That warning alone does not indicate a failed native installation.

These instructions apply to global npm installations. For installations managed through the Homebridge apt package or Docker image, follow the update instructions for that installation method.

If the UI does not appear at all, or it sits on Waiting for the Homebridge UI server..., then the UI is not running or cannot be reached. Homebridge itself may still be running normally — the UI is a separate web server that runs alongside it.

1. Check the address. By default the UI runs on port 8581, for example http://homebridge.local:8581 or http://<your-server-ip>:8581. If homebridge.local does not work, try the IP address of your server instead.

2. Start the service. From a terminal on the server:

hb-service start

If it is already running but not answering, restart it:

hb-service restart

3. Read the logs. These will usually say why it stopped:

hb-service logs

See Homebridge Service Command for the full list of commands.

• Docker — restart the container, as the UI runs inside it. See Enabling UI with Docker.
• Standalone mode — the UI runs as its own process rather than as part of the service. See Standalone Mode.
• Behind a reverse proxy — check the proxy is running and still pointing at the right port. See Reverse Proxy: Nginx and SSL or Reverse Proxy: Apache.

To fix this, Reset 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.

If the UI no longer loads at http://homebridge.local (or your hostname) but still works via the IP address, the Matter bridge's own mDNS responder may be competing with your system's mDNS service (such as avahi) for IPv4 traffic on port 5353.

To fix this, make the Matter mDNS responder IPv6-only:

1. In the UI, go to Settings and enable Disable IPv4 (Matter) (requires Homebridge v2.2.0 and UI v5.26.0 or later).
2. For Matter child bridges, the same toggle is in the plugin's bridge settings.
3. Restart Homebridge.

This is safe on almost all networks — Matter requires IPv6, and Apple hubs communicate with Matter devices over IPv6. See mDNS Options for the full explanation.

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 or
  • DOS filters on https://registry.npmjs.org/, stopping homebridge for an hour should reset them.
• 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 homebridge

The hb-service update-node command checks whether your system meets its GLIBC requirement. If the check fails, it reports Your version of Linux does not meet the GLIBC version requirements to use this tool to upgrade Node.js.

To check your GLIBC version, run getconf GNU_LIBC_VERSION on Linux or Raspberry Pi OS.

These are the GLIBC minimums checked by the current Homebridge updater. Node.js 18 and 20 are included for historical reference; see supported Node.js versions before choosing a version. Meeting the GLIBC minimum alone does not guarantee compatibility with every platform or native plugin.

Older Homebridge UI versions may enforce a higher GLIBC requirement. If the error reports a higher minimum than this table, check your Homebridge UI version and update it to a version compatible with your current Node.js installation before retrying. An OS upgrade may not be necessary if your system already meets the current requirement.

If your system's GLIBC version is below the required minimum, upgrade to an operating system release that provides a supported version. Depending on your distribution and upgrade path, you may be able to upgrade in place or may need to rebuild your setup. Create a Homebridge backup before upgrading. If you perform a fresh installation, restore the backup to recover your configuration and HomeKit pairing information. For SD-card installations, using a new card lets you retain the existing card as an additional backup.

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