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 onto the next problem.
To run Homebridge in full debug mode run the following command
DEBUG=* homebridge -D.
Validate config.json format
By far the most common issues new homebridge users run into is formatting their configuration file. Many users will have misplaced comma for example.
As a side effect, most utilities format your configuration.
Understanding where your files are (macOS)
Users running homebridge on macOS may have difficulty locating their homebridge install and logs. This is because homebridge is installed in a hidden folder that begins with a period:
By default, macOS hides folders and files that start with a "period". To toggle the visibility of these hidden files and folders, open a finder window and use the following shortcut:
Once hidden file/folder visibility is toggled to the on position, navigate to
Users/Your_Username and the
.homebridge folder will be visible.
Configuring homebridge with platforms and accessories typically requires a lot of trial and error. This applies both to the software setup, and adding accessories to HomeKit.
If you are stuck, you can reset homebridge/homekit and start again. Here's how:
- Delete any homebridge platforms/accessories from your Home app.
- Delete/remove any homebridge platforms/accessories from homekit.
- Delete all the files in the
cd ~/.homebridge rm -rf persist. If you prefer using a gui to access the files use
- Change your username in
- Restart your computer/server (advanced users can quit/restart homebridge and any boot processes rather than reboot).
Home couldn't connect to this accessory
Once you have homebridge successfully running, you may also get errors in the Home app when adding accessories. One common error occurs after scanning the QR code. While tryin to connect for 20 seconds or so, the following error is displayed:
Home couldn't connect to this accessory.
This appears to result from some cache issue in the Home app as resetting homebridge (above) does not resolve the issue. This WiFi trick appears to work however:
- Reset Pairing/Accessories as described above.
- On your iOS device, use the
Forget Networkfeature in your WiFi settings.
- Rejoin your WiFi network.
- Attempt to add the homebridge platforms/accessories as you normally would.
Examine logs for errors
Homebridge logs to two places:
PROTIP: unix has the
tail command, it makes it really nice to see logs in real time.
Assuming you have homebridge running, from that server run one of the following commands to see what is getting logged live.
tail -f /var/log/homebridge.log tail -f /var/log/homebridge.err
Error - Not a valid username
This error results from a problem in the config.json file and may look something like this:
Receiving " Error: Not a valid username: DD: 33: 4E: F4: DF: 31 . Must be 6 pairs of colon-separated hexadecimal chars (A-F 0-9), like a MAC address."
In this example the issue is the second "D". The correctly formatted version would look like "D3:33:4E:F4:DF:31".
Error - EADDRINUSE
This error is a Generic TCP/IP message thrown by nodejs apps trying to listen on a port already being listened to. This is normally caused by a homebridge process running in the background without you realizing it. If you've set your homebridge install to run when your system starts up, try removing this until your setup/config is complete.
Are you trying to setup Remote Access to your homebridge server/computer? You'll need to search for resources specific to remote access to your system (ubuntu, Windows, Apple, etc...
Remote access support for Apple can be found here.
Best Homekit app
Originally (2016) there was some discussion about apps to use to manage homekit apps. However, many people are simply using Apple's native Home app. This is the best choice for beginners.
Alternatives to Home that are well-rated and actively developed as of this writing (Jan 2019) include Home 3 (paid) and Home Assistant (the latter is for super-advanced users who are running home-assistant.io and have integrated their homekit devices into home assistant).
Asking for help
To help problem diagnosis, please provide the following information:
- Your configuration file, please remove the sensitive information
- The part of the error log pertinent to your issue