Reporting issues

If you have an installation, a setup or a configuration issue, please use our Forum to get help. We have a big community which will help you if they can.

If you found a bug, please report it in one of our trackers. To help you and our developers identify the issue quickly, please fill out the provided template.

Finding system information

Many issue reports require details about your Home Assistant installation. To find this information:

1. Go to Settings > System > Repairs.
2. From the three dots menu, select System information.
   • This system information dialog shows your Home Assistant version, installation type, operating system, and other system details.
3. To copy the system information, at the bottom of the dialog, select the Copy button.

Description of the problem

Provide a summary of your issue and tell us what’s wrong. Tell us what you were trying to do and what happened.

There are integrations which require additional steps (installing third-party tools, compilers, etc.) to get your setup working. Please describe the steps you took and the ones to reproduce the issue if needed.

First Home Assistant version with the issue

Please provide the version that contains the issue. See Finding system information for instructions on finding the version.

Last working Home Assistant release (if known)

If possible, provide the latest release that you know was working. Home Assistant is evolving very fast and issues may already be addressed or be introduced by a recent change. See Finding system information for instructions on finding the version.

Operating environment

There are many different ways to run Home Assistant. In this section, please mention which you are using: Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports apps. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. or Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any OCI compatible runtime can be used, but the documentation focus is on Docker. [Learn more] in Docker. It would be helpful to mention which operating system you are using because not all are supported on the same level. See Finding system information for instructions on how to find this information.

Integration

Please add the link to the documentation of the integration in question. For example:

• Issue with the random sensor: /integrations/random#sensor.
• Issue with the hue integration: /integrations/hue/.

Diagnostics information

Consider uploading the diagnostics file along with your issue report to allow faster triaging and pinpointing the issue. The information contained in the generated diagnostics file is redacted to avoid any sensitive information while still remaining useful for developers to fix the issue.

Problem-relevant configuration.yaml entries

To exclude configuration issues and allow the developers to quickly test, and perhaps reproduce, your issue, add the relevant part of your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file. This file is located in your configuration folder.

sensor:
  - platform: random

Make sure that you don’t post your username, password, API key, access token or other secrets.

Traceback and log information (if applicable)

If things go wrong, there will be a so-called traceback or an error message in your logs under Settings > System > Logs. Please include this. It starts with Traceback and can contain information about where the error was triggered in the code.

Traceback (most recent call last):
...

In some cases, it is also necessary to enable debug logging to get detailed logs to triage an issue. Enabling this will instruct Home Assistant to log a lot of fine-grained information about the integration. This is helpful for debugging and fixing the issue. In contrast to the diagnostics information, debug logs are not automatically redacted. Make sure to include only the parts you think are relevant to the issue.

Download the logs and see if there are any errors related to your integration.

Additional information

This section can contain additional details or other observation. Often the little things can help as well.