home-assistant/core · error · HomeAssistantError

not_connected

Error message

not_connected

What it means

HomeAssistantError with translation key 'not_connected' raised by apple_tv service helpers when the config entry's runtime AppleTVInterface (entry.runtime_data.atv) is None. That happens when the device connection was never established or was torn down (device off, setup retried, connection lost) while the config entry still exists and services are still registered.

Source

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

    }
)

SERVICE_CLEAR_KEYBOARD_TEXT = "clear_keyboard_text"
SERVICE_CLEAR_KEYBOARD_TEXT_SCHEMA = vol.Schema(
    {
        vol.Required(ATTR_CONFIG_ENTRY_ID): cv.string,
    }
)


def _get_atv(call: ServiceCall) -> AppleTVInterface:
    """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,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Wake the Apple TV and reload the integration, confirm the config entry state is 'Loaded' before calling services
2. Pick the config entry via the entity it belongs to or verify the entry ID in Developer Tools > Services
3. If the entry repeatedly fails to connect, fix the underlying connection issue (see not ready errors) first

entry = hass.config_entries.async_get_entry(config_entry_id)
if entry.state is not ConfigEntryState.LOADED or entry.runtime_data.atv is None:
    # do not call keyboard/remote services yet

def atv_ready(entry) -> bool:
    return (
        entry.state is ConfigEntryState.LOADED
        and getattr(entry.runtime_data, "atv", None) is not None
    )

When it happens

Trigger: Calling apple_tv.set_keyboard_text / send_command / etc. with ATTR_CONFIG_ENTRY_ID pointing at an entry whose .atv is None: entry still in a retry/failed setup state, device asleep or disconnected at service call time, or setup aborted after ConfigEntryNotReady.

Common situations: Dashboards or automations invoking apple_tv services right after HA restart before the entry finished connecting; Apple TV powered off or asleep; entry in 'Failed to set up' state after a network change.

Related errors

• {address}: Authentication failed, try reconfiguring device:
• {address}: {ex}
• Protocol(s) {missing_protocols_str} not yet found for {name}
• already_in_progress
• streaming_not_supported

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