home-assistant/core · error · ConfigEntryError

invalid_bucket_name

invalid_bucket_name

Error message

Invalid bucket name

What it means

Raised as ConfigEntryError (translation_key invalid_bucket_name) by aws_s3 when head_bucket raises botocore ParamValidationError whose string contains 'Invalid bucket name' — the configured bucket string violates S3 naming rules, so boto3 refuses to even send the request.

Source

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

    data = cast(dict, entry.data)
    try:
        session = AioSession()
        # pylint: disable-next=unnecessary-dunder-call
        client = await session.create_client(
            "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,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Set the bucket field to the bare bucket name only (lowercase, no s3://, no path, no ARN), e.g. 'my-homeassistant-backups'.
2. Check S3 naming rules: 3-63 chars, lowercase letters, numbers, dots, and hyphens only; must not look like an IP.
3. Note: ParamValidationError messages not matching 'Invalid bucket name' fall through unhandled — if you see a different ParamValidationError, check for empty/None bucket config.

Example fix

# before
bucket: s3://My-Backups
# after
bucket: my-backups

import re

BUCKET_RE = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$")

def valid_bucket_name(name: str) -> bool:
    return bool(name) and bool(BUCKET_RE.fullmatch(name)) and ".." not in name and not re.fullmatch(r"[\d.]+", name)

from botocore.exceptions import ParamValidationError

try:
    await client.head_bucket(Bucket=bucket)
except ParamValidationError as err:
    if "Invalid bucket name" in str(err):
        fix_bucket_field()  # config error, not transient — do not retry

When it happens

Trigger: data[CONF_BUCKET] contains characters botocore rejects: uppercase letters, underscores, spaces, leading/trailing slashes, 's3://' scheme prefix, or a full URL pasted instead of the bare bucket name.

Common situations: User pasted the S3 URI (s3://my-bucket) or ARN instead of the bucket name; bucket name typo'd with uppercase or underscore; endpoint-style config copied from another tool.

Related errors

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

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