Skip to content

Basic Troubleshooting

Tanner Record edited this page Oct 19, 2019 · 10 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 onto the next problem.

Debug Mode

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.

To prevent these errors, use an online JSON validator like JSON Lint or one of the many utilities here: Google Search: Json Validator

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: .homebridge

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: cmd-shift .

Once hidden file/folder visibility is toggled to the on position, navigate to Users/Your_Username and the .homebridge folder will be visible.

Reset Pairing/Accessories

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:

  1. Delete any homebridge platforms/accessories from your Home app.
  2. Delete/remove any homebridge platforms/accessories from homekit.
  3. Delete all the files in the .homebridge/persist and .homebridge/accessories. Eg. cd ~/.homebridge rm -rf persist. If you prefer using a gui to access the files use open ~/.homebridge.
  4. Change your username in config.json.
  5. 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:

  1. Reset Pairing/Accessories as described above.
  2. On your iOS device, use the Forget Network feature in your WiFi settings.
  3. Rejoin your WiFi network.
  4. Attempt to add the homebridge platforms/accessories as you normally would.

Examine logs for errors

Homebridge logs to two places:

  1. /var/log/homebridge.log
  2. /var/log/homebridge.err

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".


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.

Remote Access

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 and have integrated their homekit devices into home assistant).

Asking for help

To help problem diagnosis, please provide the following information:

  1. Your configuration file, please remove the sensitive information
  2. The part of the error log pertinent to your issue
You can’t perform that action at this time.