home-assistant/core · error · ServiceValidationError

keyboard_not_available

Error message

keyboard_not_available

What it means

ServiceValidationError with translation key 'keyboard_not_available' raised when querying pyatv's atv.keyboard.text_focus_state raises NotSupportedError - the connected device does not implement the keyboard/text-input protocol at all. Validation happens before any text is sent, so the service call fails fast with a user-facing validation message.

Source

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

    """Get the AppleTVInterface for a service call."""
    entry = service.async_get_config_entry(
        call.hass, DOMAIN, call.data[ATTR_CONFIG_ENTRY_ID]
    )
    atv: AppleTVInterface | None = entry.runtime_data.atv
    if atv is None:
        raise HomeAssistantError(
            translation_domain=DOMAIN,
            translation_key="not_connected",
        )
    return atv


def _check_keyboard_focus(atv: AppleTVInterface) -> None:
    """Check that keyboard is focused on the device."""
    try:
        focus_state = atv.keyboard.text_focus_state
    except NotSupportedError as err:
        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(

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify the entry has the Companion protocol connected (reconfigure so device discovery includes it) and tvOS supports the remote keyboard
2. Update tvOS on the device; older devices without keyboard support cannot use these services
3. Use button-sequence automation (send_command) as an alternative on unsupported devices

def keyboard_supported(atv) -> bool:
    try:
        _ = atv.keyboard.text_focus_state
        return True
    except NotSupportedError:
        return False

try:
    focus = atv.keyboard.text_focus_state
except NotSupportedError:
    skip_keyboard_services()  # device cannot do keyboard input

When it happens

Trigger: Calling any apple_tv keyboard service (set/append/clear text) on a device where pyatv raises NotSupportedError for keyboard.text_focus_state: tvOS too old for the Remote keyboard protocol, or device exposing no keyboard service over the Companion/MRP channel.

Common situations: Older Apple TVs (tvOS < 13ish) or Apple TV clones/airplay-only entries used with keyboard services; feature assumed available because the entity exists but the protocol was never paired; entry connected via AirPlay only without Companion.

Related errors

• keyboard_error
• {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/956e6235d54c0c21. Report an issue: GitHub.