Get a specific repair issue: issue

The issue template function looks up a specific repair issue by its domain and issue ID. Repair issues are problems that Home Assistant has detected and flagged for your attention. This function returns the issue as a dictionary if it exists, or None if no such issue is found.

This is useful when you want to check whether a specific known issue is currently present. For example, you might want to monitor whether a particular integration has a configuration problem, display the status of a specific repair on your dashboard, or trigger an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more] only when a specific issue is present.

Usage

Here’s how to use this template function. Copy any example and adjust it to your setup.

{{ issue("backup", "automatic_backup_failed") }}

{'domain': 'backup', 'issue_id': 'automatic_backup_failed', 'dismissed_version': None, ...}

{{ "backup" | issue("automatic_backup_failed") }}

{'domain': 'backup', 'issue_id': 'automatic_backup_failed', 'dismissed_version': None, ...}

Function signature

The signature is a technical summary of this template function. It shows the name of the function, the values (called parameters) it accepts, and what type of data each parameter expects (for example, a piece of text or a number).

Function parameters that have a = with a value after them are optional. If you leave them out, the default value shown is used automatically.

Function parameters without a = are usually required. A few optional parameters have no default value, so the signature shows them without a = as well. To check whether a parameter is required, look at the parameter list below the signature. Each parameter is marked as Required or Optional.

The most common optional parameter without a default value is default. The default parameter sets the value a function returns when the function can’t produce a result, for example, when float gets text that isn’t a number. If you leave out default, there is no fallback value, so most functions raise an error and the template fails. The parameter list of each function says what happens. If you set default, the function returns your value instead.

round(
    value: Any,
    precision: int = 0,
    method: str = "common",
    default: Any,
) -> float | int | Any

issue(
    domain: str,
    issue_id: str,
) -> dict[str, Any] | None

Function parameters

The following parameters can be provided to this function.

Issue details

Every returned issue contains these keys:

• domain: The integration that created the issue.
• issue_id: The unique identifier for the issue within the domain.
• created: When the issue was first raised, as an ISO 8601 timestamp string.
• dismissed_version: The Home Assistant version in which you ignored the issue, or None if you haven’t ignored it.
• config_entry_id: The ID of the integration entry that raised the issue, or None if the issue isn’t tied to an entry.
• is_persistent: Whether Home Assistant keeps the issue across restarts.

Most issues are not persistent. Only persistent issues (where is_persistent is true) also include details like severity, translation_key, translation_placeholders, learn_more_url, and breaks_in_ha_version. When severity is present, it is critical, error, or warning. Settings > System > Repairs shows a severity for every issue, but templates only get severity for persistent issues.

Checking if an issue exists

Since the function returns None when the issue is not found, you can use it directly in conditions.

{% if issue("backup", "automatic_backup_failed") %}
  Backup issue found
{% else %}
  No backup issue
{% endif %}

Backup issue found

Good to know

• Returns None when the issue does not exist, so checks like if issue(...) work directly.
• Issues you ignored are returned too. An ignored issue has a dismissed_version, so check that key if you only care about issues you haven’t ignored.
• Issues from integration entries you disabled are returned too, even though issues leaves them out.
• After a restart, this function can return an issue from before the restart that the integration hasn’t reported again yet.
• Details like severity are only available for persistent issues. Check that a key exists before you use it.

Try it yourself

Ready to test this? Open Settings > Tools > Template, paste the example into the Template editor, and watch the result update on the right. Edit the values to see how the function adapts to your own entitiesAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more].

More examples

Real scenarios where this function comes up in automations and templates. Copy any example and adapt it to your setup.

Show whether an issue is ignored

Look up a specific issue and show whether you ignored it.

{% set backup_issue = issue("backup", "automatic_backup_failed") %}
{% if not backup_issue %}
  No issue found
{% elif backup_issue.dismissed_version %}
  Backup issue ignored in {{ backup_issue.dismissed_version }}
{% else %}
  Backup issue is open
{% endif %}

Backup issue is open

Conditional notification based on issue

Send a notification only when a specific repair issue exists and you haven’t ignored it.

actions:
  - condition: template
    value_template: >
      {% set zwave_issue = issue("zwave_js", "invalid_server_version") %}
      {{ zwave_issue is not none and not zwave_issue.dismissed_version }}
  - action: notify.mobile
    data:
      message: "Z-Wave server version isn't supported. Check repairs."

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with your template and expected result, or share on our subreddit /r/homeassistant.

Related template functions

These functions work well alongside this one:

• Get all repair issues: issues - Returns all current repair issues in Home Assistant, including ignored ones.