From c300493ec22d436ec6b26e90d3f1bfba4c6d0a7f Mon Sep 17 00:00:00 2001
From: kernelpanic85 <80057019+kernelpanic85@users.noreply.github.com>
Date: Mon, 3 Mar 2025 11:20:25 -0500
Subject: [PATCH] Document HEOS clear playlist behavior (#37781)

* Add clear playlist limitation to HEOS docs

Clear playlist action generates an error if the playlist is already empty and will halt automations after home-assistant/core#136049. Referenced in issue home-assistant/core#139659. Documenting the workaround.

* Move update to actions section

* Tweak language

---------

Co-authored-by: Andrew Sayre <6730289+andrewsayre@users.noreply.github.com>
---
 source/_integrations/heos.markdown | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/source/_integrations/heos.markdown b/source/_integrations/heos.markdown
index f65dadcb4af..2fc94248dd9 100644
--- a/source/_integrations/heos.markdown
+++ b/source/_integrations/heos.markdown
@@ -204,6 +204,11 @@ data:
 
 The HEOS integration makes available the standard [Media Player actions](/integrations/media_player#actions).
 
+{% note %}
+
+Actions may fail if they cannot be processed by the HEOS device. For example, attempting to call `media_player.clear_playlist` when the queue is empty will result in an error. To prevent this from halting a script or automation, set [`continue_on_error: true`](/docs/scripts/#continuing-on-error) in the action call.
+{% endnote %}
+
 ## Supported devices
 
 Denon and Marantz do not currently publish an inventory of HEOS-enabled devices, however, many receiver and hi-fi products began including HEOS since 2013. Consult your product model to confirm support: