{"record":{"id":"699fca74578f8855","repo":"home-assistant/core","slug":"stream-failed","errorCode":null,"errorMessage":"stream_failed","messagePattern":"stream_failed","errorType":"exception","errorClass":"HomeAssistantError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/apple_tv/media_player.py","lineNumber":406,"sourceCode":"            else:\n                raise HomeAssistantError(\n                    translation_domain=DOMAIN,\n                    translation_key=\"streaming_not_supported\",\n                )\n        except exceptions.NotSupportedError as ex:\n            raise HomeAssistantError(\n                translation_domain=DOMAIN,\n                translation_key=\"streaming_not_supported\",\n            ) from ex\n        except (\n            exceptions.BlockedStateError,\n            exceptions.ConnectionLostError,\n            exceptions.InvalidStateError,\n            exceptions.OperationTimeoutError,\n            exceptions.PlaybackError,\n            exceptions.ProtocolError,\n        ) as ex:\n            raise HomeAssistantError(\n                translation_domain=DOMAIN,\n                translation_key=\"stream_failed\",\n            ) from ex\n\n    @property\n    @override\n    def media_image_hash(self) -> str | None:\n        \"\"\"Hash value for media image.\"\"\"\n        state = self.state\n        if (\n            self.atv\n            and self._playing\n            and self._is_feature_available(FeatureName.Artwork)\n            and state not in {None, MediaPlayerState.OFF, MediaPlayerState.IDLE}\n        ):\n            return self.atv.metadata.artwork_id\n        return None\n","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/apple_tv/media_player.py#L388-L424","documentation":"HomeAssistantError with translation key 'stream_failed' raised when the streaming/play call fails with one of several runtime pyatv exceptions: BlockedStateError, ConnectionLostError, InvalidStateError, OperationTimeoutError, PlaybackError, or ProtocolError. It signals that the operation was supported and attempted but failed in flight, unlike streaming_not_supported.","triggerScenarios":"stream_file/play_url raising: connection dropped mid-stream (ConnectionLostError), device refused playback (PlaybackError, e.g. unsupported codec/container over RAOP), operation timed out waiting for device response, or the device was in a state that blocks the operation (screensaver/auth prompt, BlockedStateError).","commonSituations":"Streaming a codec Apple TV cannot decode; Apple TV showing a password/purchase dialog blocking playback; Wi-Fi drop mid-cast; transient protocol errors on older tvOS; server hosting the URL unreachable from the TV (PlaybackError from AirPlay failure).","solutions":["Verify the media is in a format the Apple TV supports (ALAC/AAC over RAOP; MP4/HLS via AirPlay URL) and re-encode if needed","Ensure the URL host is reachable from the Apple TV itself, not just from HA","Retry after confirming the device is awake and no modal dialog is blocking playback; check pyatv debug logs for the specific exception to narrow the cause"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await self.atv.stream.play_url(url)\nexcept (exceptions.PlaybackError, exceptions.ConnectionLostError,\n        exceptions.OperationTimeoutError, exceptions.ProtocolError) as ex:\n    _LOGGER.warning(\"Stream failed: %s\", ex)\n    # optional single retry after device wake / network settle","preventionTips":["Pre-encode media into Apple TV-friendly formats","Confirm the URL host is reachable from the TV","Retry once after confirming no modal dialog blocks playback"],"tags":["home-assistant","apple-tv","media-player","playback","pyatv"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}