How to Troubleshoot Apps or Devices

How to Troubleshoot Apps or Devices

Is an app not working as expected? Or, is a device not working like you think it should? If so, start here for some troubleshooting tips!

App Troubleshooting

Is an app not working as expected? For example:

• Rule Machine, Basic Rule, Simple Automation Rule, or other app fails to turn on/off device when you think it should;
• Motion Lighting does not turn on or off lights when you think they should; or
• Any problem you believe to be related to an app (automation) you have configured on your hub.

If so, here are some tips that may help.

Enable Logging

Most apps have one or more types of logging that can be enabled. For example, Rule Machine rules have a Logging option that allows you to enable one or more of Trigger, Action, and Event logging. Enabling Action logging in particular will tell you what actions the rule is executing when (though enabling all may be helpful) and is a good first step to answering questions like "why didn't my rule run?" (perhaps it did and your devices simply didn't respond as expected, or it will reveal issues with your rule logic):

Most simpler apps have a toggle to enable all logging. For example, in Motion Lighting:

Other apps may have different options (and custom/community apps may vary), but most built-in apps offer one or more logging options similar to the above that may help.

Check Logs

Check the Logs page (current logs or past logs) to view logs that apps may generate if logging is enabled as described above. You may also wish to scan Logs or Past Logs for "error" or "warning" entries, which may indicate a problem. You may find errors or warning entries in many cases either with or without any app (or device) logging specifically enabled.

Verify Configuration

Ensure the options you have selected in the app are the correct selections to achieve your desired outcome. The Apps documentation section may be helpful. For Rule Machine rules or other complicated (or not!) apps, it may be helpful to ask the Community to look at your rule or other app configuration. For rules, it is generally helpful to post:

• A screenshot or description of your entire rule, including triggers and actions to run (and required expression, if used)
• A description of what you want the rule to do (in plain language, not thinking of rule implementation details)
• A screenshot of any relevant output from "Logs" (try enabling them as described above if you believe the actions are not running when or how you think they should)

Test Devices

If the app appears to be configured correctly and logging suggests it should be sending commands to devices correctly, perhaps there is a problem with the device. Try navigating to Devices, selecting the device in question, and manually running commands (buttons at the top of the device detail page) to see if they work as expected. For example, a switch device may present On and Off commands, and they would be a good idea to test if you're troubleshooting an app that is supposed to turn the device on or off.

Device Troubleshooting

Is a device not working as you expect? For example:

• A device is not updating states (e.g., on/off switch state) on the hub when the actual device changes or doesn't appear to respond to commands;
• A device is unable to be paired to the hub; or
• Any problem you believe to be related to a device you have added to your hub.

NOTE: If the problematic device is a Z-Wave device (or you are experiencing general Z-Wave network problems), see also: How to Troubleshoot Z-Wave.

Test Device

To help verify if a device is working correctly, try navigating to Devices, selecting the device in question, and manually running commands (buttons at the top of the device detail page) to see if they work as expected. The goal is to test by manually running commands from the device page to see if the command works here; if it does not, then it will not work with any app, either (including Hubitat® Dashboard, Rule Machine, Motion Lighting, or any built-in or custom app).

For example, a dimmer or bulb should have a Set Level command (and many others). For this command, type a level value (for example, 50), then select the Set Level button itself to run the command. Verify that the device responds as expected. Try other commands if needed, ideally ones you think the app would be calling based on what the app should be doing, if you are troubleshooting a device as part of an app/automation.

If commands appear to work here, additional troubleshooting with the app in question may be necessary (see above).

Enable Logging

Most device drivers offer an Enable debug logging option, which (when enabled) will generally log information that comes into the hub from the device. This can be helpful to determine if/how this information becomes an event, such as "switch on" or "level is 50%" but provides view closer to the "raw" data from the device before it gets parsed into an event (or not). Some drivers may also log when commands are executed, but not all do; most apps offer an option that will indicate when they are running a command (see above) and will be more helpful in such cases.

NOTE: Debug logging is enabled by default when new devices are added, then turned off automatically after 30 minutes. It is also automatically disabled 30 minutes after any time it is manually enabled. The descriptionText logging option is enabled by default and remains enabled until manually disabled.

Most drivers also offer an Enable descriptionText logging option. This generally logs events, like "switch on" or "thermostat operating state is heating." This does not show when commands are executed, simply when the device sends information to the hub and the driver creates an event. Its use in troubleshooting is therefore more limited than debug logging on devices or most app logging, but it may still be helpful.

These descriptions apply to built-in drivers. Custom code (community drivers) may vary, though third-party developers are encouraged to offer similar options.

Check Logs

Check the Logs page (current logs or past logs) to see logs that device drivers may generate if logging is enabled as described above.

With or without logging enabled, errors that the driver does not handle are automatically logged. Thus, even before enabling logging, you can still scan the Logs page for "error" entries that may indicate a problem (but it is generally helpful to enable).

Here is an example of en error entry in Logs (circled in red for clarity here; your logs will not show this circle):

Other Device Troubleshooting

• Check the Compatible Device List to verify you are using the recommended built-in driver for your specific device (or for third-party code, verify that the driver is supposed to be compatible)
• It is generally recommended to run the Configure command on the device page after switching drivers. Try this if you haven't.
• The Configure command can also be run manually as part of troubleshooting specific device problems, including a Zigbee device not reporting updated states back to the hub as expected (note that you will not see anything happen on the device page when this command is executed; you may see entries in Logs)

Select (click or tap) the "Configure" button to execute the command, then wait a few seconds. Normally, you will not see anything happen after executing the command, but it may be important in order for the driver to work correctly.

Soft Reset

For cases of suspected database corruption (for example, apps with "Scheduled Jobs" that appear to be scheduled correctly but do not execute when expected; SQL errors in Logs; and others), a soft reset and restore from a backup may help. A soft reset does not affect the Z-Wave and Zigbee radios and is thus a generally safe procedure. To perform a soft reset:

1. Download a backup from Settings > Backup and Restore by selecting Download under Create New Backup and Download Locally.
   • Save this file locally to your computer (Hub Protect subscribers may opt to make a cloud backup instead)
   • You will need to restore this backup, as below, after the soft reset in order to use all your devices, apps, etc. as before (the soft reset does not clear the Z-Wave or Zigbee radios but does remove all devices from your Devices list; the backup will restore them).
2. Navigate to the Hubitat Diagnostic Tool from Settings > Diagnostic Tool.
3. Select Soft Reset and follow the prompts.
   • You may wish to navigate to Settings > Hub Details before this to obtain the MAC address of your hub, which you may be prompted for.
4. When the hub reboots after the soft reset, select the Restore from backup? link at the bottom of the Getting Started screen, then select the backup you downloaded in step 1 as the file to restore, follow the prompts, and wait for the process to complete.
5. The hub will automatically reboot when finished, now operating with the restored/cleaned database.

Problems After Upgrading?

Did you recently update your hub and suspect that the upgrade "broke" an existing device or automation? Hubitat allows you to downgrade to up to three previously installed platform versions. You can downgrade to test again and verify your suspicion.

1. Optional, but recommended: download a backup from Settings > Backup and Restore by selecting Download under Create New Backup and Download Locally.
   • Save this file locally to your computer (Hub Protect subscribers may opt to make a cloud backup instead)
2. Navigate to the Hubitat Diagnostic Tool from Settings > Diagnostic Tool.
3. Select Restore Previous Version and select the specific previous version to which you wish to restore.
4. Wait for the process to complete. The hub will automatically reboot.
5. Re-test the app or automation. (Optionally, re-upgrade to verify the problem re-appears and was not addressed by a simple reboot.) If you believe you have found a problem, you may wish to ask about it in the Hubitat Community.