home-assistant/core · error · HomeAssistantError

keyboard_error

keyboard_error

Error message

An error occurred while sending text to the Apple TV

What it means

HomeAssistantError with translation key 'keyboard_error' raised when atv.keyboard.text_set(text) fails with a pyatv ProtocolError while the keyboard service tries to set the input field text. The keyboard feature exists and was focused, but the underlying protocol exchange with the device failed.

Source

Thrown at homeassistant/components/apple_tv/services.py:76

        raise ServiceValidationError(
            translation_domain=DOMAIN,
            translation_key="keyboard_not_available",
        ) from err
    if focus_state is not KeyboardFocusState.Focused:
        raise ServiceValidationError(
            translation_domain=DOMAIN,
            translation_key="keyboard_not_focused",
        )


async def _async_set_keyboard_text(call: ServiceCall) -> None:
    """Set text in the keyboard input field on an Apple TV."""
    atv = _get_atv(call)
    _check_keyboard_focus(atv)
    try:
        await atv.keyboard.text_set(call.data[ATTR_TEXT])
    except ProtocolError as err:
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="keyboard_error",
        ) from err


async def _async_append_keyboard_text(call: ServiceCall) -> None:
    """Append text to the keyboard input field on an Apple TV."""
    atv = _get_atv(call)
    _check_keyboard_focus(atv)
    try:
        await atv.keyboard.text_append(call.data[ATTR_TEXT])
    except ProtocolError as err:
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="keyboard_error",
        ) from err

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Retry after confirming the text field is still open and focused on the device
2. Reduce payload size / send text in append chunks for long strings
3. If it repeats, reload the integration to re-establish the Companion session and check network stability

try:
    await atv.keyboard.text_set(text)
except ProtocolError as ex:
    _LOGGER.warning("keyboard set failed: %s", ex)
    await asyncio.sleep(1)
    # one bounded retry after re-checking focus

When it happens

Trigger: Calling apple_tv.set_keyboard_text on a focused keyboard field where pyatv raises ProtocolError: device dropped the session mid-write, companion connection reset, or the tvOS keyboard session expired between focus check and text_set.

Common situations: Search/password fields on Apple TV that closed while the automation was sending text; network hiccup between HA and the TV; long text payloads timing out the companion channel; device locked mid-operation.

Related errors

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

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