home-assistant/core · warning · PipelinePreferred

Item {item_id} preferred.

Error message

Item {item_id} preferred.

What it means

PipelinePreferred (a CollectionError) is raised by PipelineStorageCollection.async_delete_item when a caller tries to delete the pipeline that is currently marked as preferred (self._preferred_item). The collection refuses the delete so the instance always has a valid preferred/default pipeline.

Source

Thrown at homeassistant/components/assist_pipeline/pipeline.py:1980

    def _create_item(self, item_id: str, data: dict) -> Pipeline:
        """Create an item from validated config."""
        return Pipeline(id=item_id, **data)

    @override
    def _deserialize_item(self, data: dict) -> Pipeline:
        """Create an item from its serialized representation."""
        return Pipeline.from_json(data)

    @override
    def _serialize_item(self, item_id: str, item: Pipeline) -> dict:
        """Return the serialized representation of an item for storing."""
        return item.to_json()

    @override
    async def async_delete_item(self, item_id: str) -> None:
        """Delete item."""
        if self._preferred_item == item_id:
            raise PipelinePreferred(item_id)
        await super().async_delete_item(item_id)

    @callback
    def async_get_preferred_item(self) -> str:
        """Get the id of the preferred item."""
        return self._preferred_item

    @callback
    def async_set_preferred_item(self, item_id: str) -> None:
        """Set the preferred pipeline."""
        if item_id not in self.data:
            raise ItemNotFound(item_id)
        self._preferred_item = item_id
        self._async_schedule_save()

    @callback
    @override
    def _data_to_save(self) -> SerializedPipelineStorageCollection:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. First set another pipeline as preferred (async_set_preferred_item or the UI), then delete the old one.
2. If it is the only pipeline, create a replacement pipeline before deleting.
3. Catch PipelinePreferred in API clients and surface 'cannot delete the preferred pipeline' to the user.

Example fix

# before
await pipeline_data.async_delete_item(pipeline_id)  # raises if preferred

# after
from homeassistant.components.assist_pipeline.pipeline import PipelinePreferred
try:
    await pipeline_data.async_delete_item(pipeline_id)
except PipelinePreferred:
    raise ValueError("Set another pipeline as preferred before deleting this one")

if pipeline_data.async_get_preferred_item() == pipeline_id:
    raise ValueError("Cannot delete the preferred pipeline; pick another first")

from homeassistant.components.assist_pipeline.pipeline import PipelinePreferred
try:
    await pipeline_data.async_delete_item(pipeline_id)
except PipelinePreferred:
    ...  # tell the user to set another pipeline as preferred

When it happens

Trigger: Calling pipeline_data.async_delete_item(preferred_id) via the storage collection API (config flow, WebSocket command assist_pipeline/delete, or service code) while that id is the active preferred pipeline.

Common situations: Deleting the default pipeline from the UI while a satellite points at 'preferred'; scripts iterating over pipelines and deleting all of them; deleting the last remaining pipeline.

Related errors

• Item {item_id} not found.
• pipeline_not_found
• noise_suppression_level must be in [0, 4]
• auto_gain_dbfs must be in [0, 31]
• validation-error

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/a523defe9f952932. Report an issue: GitHub.