Support & Troubleshooting

Support

This is just a personal project that I started many years ago and was crazy enough to share publicly. When the project was small I tried to address every user issue but the project only supported a small number of devices and had only a few users and using the project required a fairly high technical competency. Now the Ring ecosystem is much larger, and this project supports dozens of device types and variations, including many I don't own myself. On top of this the project is now estimated to have >10,000 individual installs, most with the HA addon and many who have fairly limited understanding of how everything works under the covers.

This success means that it is simply impossible for me to provide support for basic setup issues or problems, I simply do not have the time to individually answer questions about how to configure this project. However, over the course of the last 5+ years this project has become quite stable, and nearly every setup or configuration issue has already been reported, many times including a solution.

To take advantage of this existing knowledge please search for your issue using various methods prior to posting any new support related questions. If you are unable to find any solution via search, you are welcome to post about the issue in the Support Q&A discussion group and hopefully someone will either be able to share their experience, or I will have time to answer or offer suggestions.

Troubleshooting

While ring-mqtt is fairly reliable, it's still a reverse engineered solution. One of the most difficult issues to deal with is recovery from various unexpected events, since we have no way of testing those events ourselves, thus various outage conditions and can lead to cases where ring-client-api does not automatically recover. Below are some common issues and simple steps that can be used to resolve them.

No motion/ding state updates for cameras/intercoms

While Ring alarm devices provide near real-time state updates via websocket, Ring cameras and intercoms do not offer such an API. There are only two ways to get events from these devices, either by polling the Ring API every few seconds, or by registering to receive push notifications (the same ones you get on your phone when using the Ring app). Push notifications are used by ring-mqtt as they are the fastest method and include useful metadata such as the UUID of the snapshot taken when the motion/ding was triggered, allowing ring-mqtt to provide the same snapshot available in the Ring app. For various reasons, it's possible that delivery of push notifications will stop working and thus motion/ding states for these devices will no longer be updated. If this happens, please use the following steps to force a re-registration with the push notification service:

1. Open the ring-mqtt web UI and note the device name
2. Stop the ring-mqtt addon/container
3. Navigate to the Ring Control Center using the Ring App or Ring Web console (Located in Account settings)
4. Locate the device with the matching device name from step 1 in Authorized Client Devices and delete it
5. It's also a good idea to clean up any old, unused devices here as well as this can sometimes cause issues
6. Restart the addon and use the addon web UI to re-authenticate to the Ring API

All devices suddenly offline

If ring-mqtt was previously running fine and you suddenly lose all entities, follow these steps:

1. Restart the addon
   This is all that is required ~90% of the time. Restarting the addon seems obvious and I'm not sure why people don't just do this as a matter of course but I think the biggest reason is that the UI to restart Home Assistant does not actually restart the addons unless the the advanced options are expanded and "Reboot System" is chosen. Without this step, only the container running the Home Assistant core code is restarted while the addon containers just stay running, but most users don't seem to realize this. Each addon has it's own restart button and can be restarted individually, or you can choose to reboot the host system entirely. If an initial restart does not fix the problem, you may want to stop the addon for several hours, or even a day, before starting it back as, in some cases, constantly attempt to connect with an invalid token triggers Ring to block the IP temporarily. Simply waiting a few hours without login attempt will usually be enough for the temporary IP block to be removed. If you are seeing authentication errors even after acquiring a new token, this is the most likely cause.

2. Make sure all hub devices are online
   This is the second most common issue reported. During startup, ring-mqtt attempts to discover all devices the account has access to, including any devices on shared accounts. Any offline hubs (alarms, smart lighting, etc) will cause this discovery process to hang waiting for the devices to come online before continuing. I try to make this very clear in the logs, but it seems many people do not even bother to read the logs, even though that is the only way to troubleshoot anything.

3. Stop addon/Remove authorized device(s) from Ring Control Center/Start addon/Re-authenticate
   This works for almost all of the remaining cases and is basically the same steps Ring recommends when the Ring app malfunctions and can't view devices, etc.

4. Remove and re-install addon
   This is needed maybe .001% of the time, usually only if the container won't start for some reason or exits immediately. This is brute force, it will work, because the new install gets a new hardware ID generated, which will create a new device registration with Ring, but in the vast majority of cases it would have been possibly to just follow step 3 and removed the old device from Ring Control Center to get the same effect. The biggest down side of this approach is that you lose any device specific settings like snapshot frequency, bypass settings, etc. If you just use 100% default settings for all devices, or you only have a few devices, well, no big deal I guess, but you do also leave old, unused devices registered in Ring, which can negatively impact notifications if you get too many of them.