mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-28 11:47:00 +00:00
update the Troubleshooting Automations page (#31810)
* update the Troubleshooting Automations page * fix style for linter * clarifying a couple spots * clarifying triggers * Style tweaks * tiny style tweak * Apply suggestions from code review * Update source/_docs/automation/troubleshooting.markdown --------- Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
John Taseff
GitHub
parent
e8a1a9d19f
commit
4a15a89e8b
@ -3,43 +3,72 @@ title: "Troubleshooting automations"
|
||||
description: "Tips on how to troubleshoot your automations."
|
||||
---
|
||||
|
||||
Automations and {% term scripts %} can be debugged in a few different ways. You can [test run](#testing-your-automation) the full sequence of actions, or test each condition and action separately. [Traces](#traces) let you see details of every step after an automation is run. For complicated automations with {% term templates %}, see the section [testing templates](#testing-templates).
|
||||
|
||||
## Testing your automation
|
||||
|
||||
Many automations can be tested directly in the automation editor UI.
|
||||
|
||||
### Running the entire automation
|
||||
|
||||
In the three dots menu in the automation list or automation editor UI, select the **Run** button. This will execute all of the {% term actions %}, while skipping all {% term triggers %} and {% term conditions %}. This lets you test the full sequence of actions, as if the automation was triggered and all conditions were true. Note that any [trigger ID](/automation/trigger/#trigger-id) used in your triggers will not be active when you test this way. The Trigger ID or any data passed by in the `trigger` data in conditions or actions can't be tested directly this way.
|
||||
|
||||
You can also trigger an automation manually. This can test the conditions as if the automation was triggered by an event. Navigate to {% my developer_services title="**Developer tools** > **Services**" %}. In the service selection drop-down, select **Automation: Trigger**, then **Choose entity** to select the automation you are testing. Toggle whether to skip the conditions, then **Call service**. If needed, additional `trigger` or other data can be added in the YAML view for testing. The [trigger](docs/automation/trigger/) page has more information about data within the trigger.
|
||||
|
||||
Testing with complex triggers, conditions, and variables can be difficult. Note that using the **Run** button will skip all triggers and conditions, while **Developer Tools** can be used with or without checking conditions.
|
||||
|
||||
### Running individual actions or conditions
|
||||
|
||||
In the automation editor UI, each {% term condition %} and {% term action %} can be tested individually. Select the three dots menu, then the **Test** button.
|
||||
|
||||
- Testing a condition will highlight it to show whether the condition passed at the moment it was tested. If all conditions pass, then the automation will run when triggered. Testing building blocks like an **and** condition will report whether the whole block registers as true or false, or you can test individual conditions within the building block.
|
||||
|
||||
- Testing an action block will run that block immediately.
|
||||
|
||||
Note that complex automations that depend on previous blocks, such as trigger IDs, variables in templates, or service calls that return data to use in subsequent blocks, cannot be tested this way.
|
||||
|
||||
If you are writing automations in YAML, it is also useful to go to {% my server_controls title="**Developer tools** > **YAML**" %}** and in the Configuration validation section, select the **Check configuration** button. This is to make sure there are no syntax errors before restarting Home Assistant. In order for **Check configuration** to be visible, you must enable **Advanced Mode** on {% my profile title="your user profile" %}.
|
||||
|
||||
## Traces
|
||||
|
||||
When an {% term automation %} is run, all steps are recorded and a trace is made. From the UI, open **Settings**, which is located in the sidebar, then select **Automations & Scenes** to go to the automation editor or click this button directly: {% my automations badge %}
|
||||
|
||||
Click on the clock icon next to an automation to enter the debugging screen. Alternatively, click on **Show trace** directly from a Logbook automation entry.
|
||||
From the automation editor UI, or in the automations list in the three dots menu, select **Traces**. Alternatively, select an automation entry shown in the Logbook.
|
||||
|
||||
|
||||
|
||||
The above screenshot shows a previous run of an automation. The automation is displayed using an interactive graph, highlighting which path the automation took. Each node in the graph can be clicked to view the details on what happened with the automation during that specific step. It traces the complete run of an automation.
|
||||
|
||||
The debugging screen is split into four features, the first being the Step Details which provides all details for each step of the automation. The second feature is the Trace Timeline which the screenshot above shows and where the automation can be followed on a timeline. The next is Related logbook entries, as the name says a logbook for all the entries related to the specific trace. The last two features are Automation Config and optionally Blueprint Config for the automation YAML code.
|
||||
The right side of the trace screen has tabs with more information:
|
||||
|
||||
- **Step Details** shows data and results of the step that is currently highlighted.
|
||||
- **Automation Config** shows the full YAML configuration at the time the automation was run.
|
||||
- **Trace Timeline**, shown in the screenshot above, lists the steps that were executed and their timing.
|
||||
- **Related logbook entries**, shows a logbook for all the entries related to the specific trace.
|
||||
- **Blueprint Config** will only be shown if the automation was created from a {% term blueprint %}.
|
||||
|
||||
The top bar shows the date and time the automation was triggered. Use the left and right arrows to view previous runs of the automation.
|
||||
|
||||
Automations created in YAML must have an [`id`](/docs/automation/yaml/#migrating-your-yaml-automations-to-automationsyaml) assigned in order for debugging traces to be stored.
|
||||
|
||||
#### Traces
|
||||
### Trace configuration
|
||||
|
||||
The last 5 traces are recorded for all automations. It is possible to change this by adding the following code to your automation.
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
trace:
|
||||
stored_traces: 1
|
||||
stored_traces: 20
|
||||
```
|
||||
|
||||
[template]: /docs/configuration/templating/
|
||||
{% endraw %}
|
||||
|
||||
## Testing your automation
|
||||
## Testing templates
|
||||
|
||||
It is generally a difficult task to test an automation, especially if it includes several triggers and some conditions.
|
||||
If your automation uses [templates](/docs/configuration/templating/) in any part, you can do the following to make sure it works as expected:
|
||||
|
||||
Please note that if you click on **Trigger** of an automation in the frontend, **only the `action` part will be executed** by Home Assistant. That means you **can't** test your trigger or condition part that way. It also means that if your automation uses some data from triggers, it won't work properly as well just because `trigger` is not defined in this scenario.
|
||||
|
||||
All this makes that Trigger feature pretty limited and nearly useless for debugging purposes so you need to find another way.
|
||||
Make sure you check and adapt to your circumstances appropriate examples from Automation Trigger, Conditions and Actions.
|
||||
|
||||
It is also useful to go to **{% my server_controls title="Developer Tools -> YAML" %}** and click on **Check Configuration** button in Configuration validation section to make sure there are no syntax errors before restarting Home Assistant. In order for **Check configuration** to be visible, you must enable **Advanced Mode** on {% my profile title="your user profile" %}.
|
||||
|
||||
If your automation uses templates in any part, you can do the following to make sure it works as expected:
|
||||
|
||||
1. Go to **{% my developer_template title="Developer tools -> Template" %}** tab.
|
||||
1. Go to {% my developer_template title="**Developer tools** > **Template**" %} tab.
|
||||
2. Create all variables (sources) required for your template as described at the end of [this](https://www.home-assistant.io/docs/configuration/templating/#processing-incoming-data) paragraph.
|
||||
3. Copy your template code and paste it in Template editor straight after your variables.
|
||||
4. If necessary, change your sources' value and check if the template works as you want and does not generate any errors.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user