{"record":{"id":"a523defe9f952932","repo":"home-assistant/core","slug":"item-item-id-preferred","errorCode":null,"errorMessage":"Item {item_id} preferred.","messagePattern":"Item (.+?) preferred\\.","errorType":"exception","errorClass":"PipelinePreferred","httpStatus":null,"severity":"warning","filePath":"homeassistant/components/assist_pipeline/pipeline.py","lineNumber":1980,"sourceCode":"    def _create_item(self, item_id: str, data: dict) -> Pipeline:\n        \"\"\"Create an item from validated config.\"\"\"\n        return Pipeline(id=item_id, **data)\n\n    @override\n    def _deserialize_item(self, data: dict) -> Pipeline:\n        \"\"\"Create an item from its serialized representation.\"\"\"\n        return Pipeline.from_json(data)\n\n    @override\n    def _serialize_item(self, item_id: str, item: Pipeline) -> dict:\n        \"\"\"Return the serialized representation of an item for storing.\"\"\"\n        return item.to_json()\n\n    @override\n    async def async_delete_item(self, item_id: str) -> None:\n        \"\"\"Delete item.\"\"\"\n        if self._preferred_item == item_id:\n            raise PipelinePreferred(item_id)\n        await super().async_delete_item(item_id)\n\n    @callback\n    def async_get_preferred_item(self) -> str:\n        \"\"\"Get the id of the preferred item.\"\"\"\n        return self._preferred_item\n\n    @callback\n    def async_set_preferred_item(self, item_id: str) -> None:\n        \"\"\"Set the preferred pipeline.\"\"\"\n        if item_id not in self.data:\n            raise ItemNotFound(item_id)\n        self._preferred_item = item_id\n        self._async_schedule_save()\n\n    @callback\n    @override\n    def _data_to_save(self) -> SerializedPipelineStorageCollection:","sourceCodeStart":1962,"sourceCodeEnd":1998,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/assist_pipeline/pipeline.py#L1962-L1998","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["First set another pipeline as preferred (async_set_preferred_item or the UI), then delete the old one.","If it is the only pipeline, create a replacement pipeline before deleting.","Catch PipelinePreferred in API clients and surface 'cannot delete the preferred pipeline' to the user."],"exampleFix":"# before\nawait pipeline_data.async_delete_item(pipeline_id)  # raises if preferred\n\n# after\nfrom homeassistant.components.assist_pipeline.pipeline import PipelinePreferred\ntry:\n    await pipeline_data.async_delete_item(pipeline_id)\nexcept PipelinePreferred:\n    raise ValueError(\"Set another pipeline as preferred before deleting this one\")","handlingStrategy":"try-catch","validationCode":"if pipeline_data.async_get_preferred_item() == pipeline_id:\n    raise ValueError(\"Cannot delete the preferred pipeline; pick another first\")","typeGuard":null,"tryCatchPattern":"from homeassistant.components.assist_pipeline.pipeline import PipelinePreferred\ntry:\n    await pipeline_data.async_delete_item(pipeline_id)\nexcept PipelinePreferred:\n    ...  # tell the user to set another pipeline as preferred","preventionTips":["Before delete flows, check async_get_preferred_item() and force a reselection.","Keep at least two pipelines when automating lifecycle of pipelines."],"tags":["assist-pipeline","storage","collection","delete"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}