home-assistant/core · error · ConfigEntryError

invalid_endpoint_url

invalid_endpoint_url

Error message

Invalid endpoint URL. Please make sure it's a valid AWS S3 endpoint URL.

What it means

Raised as ConfigEntryError (translation_key invalid_endpoint_url) by aws_s3 when creating the S3 client or calling head_bucket raises ValueError — botocore/awscrt rejects the configured endpoint_url because it is not a parseable URL (no scheme, malformed host, unsupported scheme).

Source

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

            "s3",
            endpoint_url=data.get(CONF_ENDPOINT_URL),
            aws_secret_access_key=data[CONF_SECRET_ACCESS_KEY],
            aws_access_key_id=data[CONF_ACCESS_KEY_ID],
        ).__aenter__()
        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:

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Enter the full endpoint URL including scheme, e.g. http://192.168.1.10:9000 or https://minio.example.com.
2. Trim whitespace and confirm the port is right; HTTPS requires a valid TLS cert on the endpoint (or use http for local LAN services).
3. For AWS itself, leave the endpoint URL empty — it is optional.

Example fix

# before
endpoint_url: 192.168.1.10:9000
# after
endpoint_url: http://192.168.1.10:9000

from urllib.parse import urlparse

def valid_endpoint_url(url: str | None) -> bool:
    if not url:
        return True  # optional for AWS
    parsed = urlparse(url)
    return parsed.scheme in ("http", "https") and bool(parsed.netloc)

try:
    client = await session.create_client("s3", endpoint_url=url, ...).__aenter__()
except ValueError:
    # endpoint is not a valid URL; fix the config, do not retry
    raise ConfigEntryError(translation_key="invalid_endpoint_url")

When it happens

Trigger: data[CONF_ENDPOINT_URL] is something like 'my-minio:9000' (missing http://), 'ftp://x', contains whitespace, or is a bare hostname; botocore's URL parsing raises ValueError before any network call.

Common situations: MinIO/other S3-compatible backends configured for the first time; user copied host:port from a docker-compose file without the scheme; trailing newline/space in a pasted URL.

Related errors

• invalid_bucket_name
• cannot_connect
• invalid_credentials
• Failed during {func.__name__}
• Failed to upload backup

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