home-assistant/core · error · HomeAssistantError

stream_failed

Error message

stream_failed

What it means

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.

Source

Thrown at homeassistant/components/apple_tv/media_player.py:406

            else:
                raise HomeAssistantError(
                    translation_domain=DOMAIN,
                    translation_key="streaming_not_supported",
                )
        except exceptions.NotSupportedError as ex:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="streaming_not_supported",
            ) from ex
        except (
            exceptions.BlockedStateError,
            exceptions.ConnectionLostError,
            exceptions.InvalidStateError,
            exceptions.OperationTimeoutError,
            exceptions.PlaybackError,
            exceptions.ProtocolError,
        ) as ex:
            raise HomeAssistantError(
                translation_domain=DOMAIN,
                translation_key="stream_failed",
            ) from ex

    @property
    @override
    def media_image_hash(self) -> str | None:
        """Hash value for media image."""
        state = self.state
        if (
            self.atv
            and self._playing
            and self._is_feature_available(FeatureName.Artwork)
            and state not in {None, MediaPlayerState.OFF, MediaPlayerState.IDLE}
        ):
            return self.atv.metadata.artwork_id
        return None

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. 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
2. Ensure the URL host is reachable from the Apple TV itself, not just from HA
3. 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

try:
    await self.atv.stream.play_url(url)
except (exceptions.PlaybackError, exceptions.ConnectionLostError,
        exceptions.OperationTimeoutError, exceptions.ProtocolError) as ex:
    _LOGGER.warning("Stream failed: %s", ex)
    # optional single retry after device wake / network settle

When it happens

Trigger: 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).

Common situations: 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).

Related errors

• streaming_not_supported
• {address}: Authentication failed, try reconfiguring device:
• Command not found. Exiting sequence
• keyboard_not_available
• keyboard_error

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