Home Assistant Guide

Simple tutorials for powerful automations

Debugging Automations and Scripts

Automations and scripts are at the heart of Home Assistant, letting you automate tasks and control devices based on conditions you define. Sometimes, though, they don't work as expected. This guide shows you how to troubleshoot your automations and scripts using Home Assistant's built-in tools, so you can find and fix problems quickly.

Why Do Automations and Scripts Fail?

  • Typos in entity IDs or service names.
  • Missing or incorrect conditions.
  • Devices that are offline or unavailable.
  • Errors in your YAML or configuration.

When something doesn't work, Home Assistant usually provides clues in its logs and traces.

Using Traces: Visual Step-Through Debugging

Traces let you see exactly how an automation or script ran, step by step, and where it might have failed.

  1. Go to Settings > Automations & Scenes and find your automation or script.
  2. Click on it, then look for the Traces option.
  3. You'll see a list of recent runs. Click one to see a visual breakdown:
    • Which trigger fired?
    • Which conditions passed or failed?
    • Which actions ran (or didn't) and in what order?
  4. Steps that failed are usually highlighted in red, with error messages or explanations.

Tip: If nothing appears in Traces, the automation or script hasn't run yet. Try triggering it manually.

Viewing Logs: Checking for Error Messages

  1. Open Settings > System > Logs in Home Assistant.
  2. Look for entries marked as ERROR or WARNING around the time your automation or script ran.
  3. Errors will often mention a missing entity, typo, or problem with your YAML.

Tip: Some errors might only appear in the more detailed logs. To view them, go to Settings > System > Logs and click "Load Full Home Assistant Log".

Manual Testing: Triggering and Editing

  • Run actions manually: On the automation or script page, click Run Actions (looks like a play button) to see if it works outside its normal trigger.
  • Edit and test small changes: Tweak one thing at a time, then test. This helps isolate what's causing the issue.
  • Check entity states: Go to Developer Tools > States and make sure the entities you're using actually exist and are in the expected state.

Common Debugging Steps (Checklist)

  • Double-check all entity IDs for typos.
  • Make sure all referenced devices are online.
  • Check conditions: Could any block the automation?
  • Look for indentation or formatting errors if editing YAML.
  • Try simplifying: Remove actions and add them back one by one.
  • Use Traces and Logs after each test.

Helpful Tools

  • Developer Tools > Services: Call services manually to check that your action (like turning on a light) works outside of the automation.
  • Developer Tools > Template: Test templates (for conditions or actions) to see if they work and return the expected result.

When to Ask for Help

If you're stuck, try searching the Home Assistant Community Forums or posting your issue. Be sure to include:

  • The automation or script YAML
  • Relevant log or trace errors (copy and paste, if possible)
  • A brief description of what you expect and what actually happens

Summary

Debugging automations and scripts can feel overwhelming at first, but Home Assistant provides excellent tools like Traces and Logs to help you see exactly what's going on. Take it step by step, and don't be afraid to experiment - the more you troubleshoot, the easier it becomes!