home-assistant/core · error · ConfigEntryNotReady

cannot_connect

cannot_connect

Error message

Cannot connect to endpoint

What it means

Raised as ConfigEntryNotReady (translation_key cannot_connect) by aws_s3 when head_bucket raises a Python ConnectionError — the TCP connection to the S3 endpoint could not be established. Home Assistant marks setup as not-ready and retries with backoff; the entry is not permanently failed.

Source

Thrown at homeassistant/components/aws_s3/__init__.py:59

        await client.head_bucket(Bucket=data[CONF_BUCKET])
    except ClientError as err:
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="invalid_credentials",
        ) from err
    except ParamValidationError as err:
        if "Invalid bucket name" in str(err):
            raise ConfigEntryError(
                translation_domain=DOMAIN,
                translation_key="invalid_bucket_name",
            ) from err
    except ValueError as err:
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="invalid_endpoint_url",
        ) from err
    except ConnectionError as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="cannot_connect",
        ) from err

    coordinator = S3DataUpdateCoordinator(
        hass,
        entry=entry,
        client=client,
    )
    await coordinator.async_config_entry_first_refresh()
    entry.runtime_data = coordinator

    def notify_backup_listeners() -> None:
        for listener in hass.data.get(DATA_BACKUP_AGENT_LISTENERS, []):
            listener()

    entry.async_on_unload(entry.async_on_state_change(notify_backup_listeners))

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify the endpoint is reachable from the HA host: curl -I http(s)://<endpoint>.
2. Fix the endpoint URL/port if the storage service moved (static IP or DNS name recommended).
3. Open outbound access to the endpoint in firewalls; for AWS ensure s3.<region>.amazonaws.com:443 is allowed.
4. No action needed for a transient outage — ConfigEntryNotReady retries automatically.

import socket
from urllib.parse import urlparse

def endpoint_connectable(url: str, timeout: float = 3.0) -> bool:
    p = urlparse(url or "https://s3.amazonaws.com")
    port = p.port or (443 if p.scheme == "https" else 80)
    try:
        socket.create_connection((p.hostname, port), timeout=timeout).close()
        return True
    except OSError:
        return False

except ConnectionError as err:
    raise ConfigEntryNotReady(translation_key="cannot_connect") from err  # HA retries with backoff

When it happens

Trigger: head_bucket to the configured endpoint fails at the network layer: endpoint host down/wrong port, DNS resolution failure, firewall dropping the connection, MinIO container restarting, or packet loss causing connect timeouts.

Common situations: Local MinIO/NAS offline or rebooting; endpoint URL points to a wrong IP after DHCP change; HA in a container without access to the storage VLAN; AWS endpoint blocked by an egress firewall.

Related errors

• invalid_endpoint_url
• Failed connecting to the websocket.
• {address}: {ex}
• Could not connect to Autoskope API
• Error communicating with API: {err}

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