home-assistant/core · warning · ItemNotFound

Item {item_id} not found.

Error message

Item {item_id} not found.

What it means

ItemNotFound (a CollectionError from homeassistant.helpers.collection) is raised by async_set_preferred_item when the given item_id is not a key in the pipeline collection's data. It guards the preferred pointer from being set to a pipeline that does not exist.

Source

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

        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:
        """Return JSON-compatible date for storing to file."""
        base_data = super()._base_data_to_save()
        return {
            "items": base_data["items"],
            "preferred_item": self._preferred_item,
        }


class PipelineStorageCollectionWebsocket(
    StorageCollectionWebsocket[PipelineStorageCollection]
):
    """Class to expose storage collection management over websocket."""

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. List current pipelines (pipeline_data.async_pipelines_items / UI) and pass a valid id.
2. Refresh any cached pipeline ids in satellite/automation state after pipelines are created or deleted.
3. Catch ItemNotFound and fall back to the current preferred item id.

Example fix

# before
await pipeline_data.async_set_preferred_item(stored_id)  # stale id -> raises

# after
from homeassistant.helpers.collection import ItemNotFound
try:
    await pipeline_data.async_set_preferred_item(stored_id)
except ItemNotFound:
    await pipeline_data.async_set_preferred_item(pipeline_data.async_get_preferred_item())

if item_id not in pipeline_data.data:
    item_id = pipeline_data.async_get_preferred_item()  # fall back to current preferred

from homeassistant.helpers.collection import ItemNotFound
try:
    await pipeline_data.async_set_preferred_item(item_id)
except ItemNotFound:
    ...  # refresh pipeline list, reselect

When it happens

Trigger: Calling async_set_preferred_item (or the corresponding WebSocket/UI action) with a pipeline id that was deleted, never existed, or came from stale state (e.g. a satellite's stored pipeline reference).

Common situations: Automations or voice satellites holding a cached pipeline id after the pipeline was recreated; race where the pipeline is deleted between a list call and the set-preferred call; typos in manually crafted ids.

Related errors

• Item {item_id} preferred.
• 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/a4bfa1fea3a016f6. Report an issue: GitHub.