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.
Solutions
- Set the bucket field to the bare bucket name only (lowercase, no s3://, no path, no ARN), e.g. 'my-homeassistant-backups'.
- Check S3 naming rules: 3-63 chars, lowercase letters, numbers, dots, and hyphens only; must not look like an IP.
- 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
Defensive patterns
Strategy: validation
Validate before calling
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)
Try / catch
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 Prevention
- Store only the bare bucket name; strip s3:// and paths in UI code before saving.
- Validate bucket names client-side with the S3 naming rules regex before setup.
- Beware the fall-through: ParamValidationError without 'Invalid bucket name' is re-raised uncaught.
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
AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14).
Data as JSON: /api/errors/39d6a681f5ea0bc2.
Report an issue: GitHub.
Appendix: 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)