home-assistant/core · error · ConfigEntryNotReady

restricted_bucket

Error message

restricted_bucket

What it means

Raised as ConfigEntryNotReady (translation key restricted_bucket) when authorize/get_bucket fails with exception.RestrictedBucket. The credentials are valid but the application key is restricted to a different bucket (or no buckets), so get_bucket_by_name for the configured bucket cannot authorize it. HA also creates a repair issue naming the bucket.

Source

Thrown at homeassistant/components/backblaze_b2/__init__.py:63

        b2sdk operations are blocking.
        """
        b2_api.authorize_account(
            BACKBLAZE_REALM,
            entry.data[CONF_KEY_ID],
            entry.data[CONF_APPLICATION_KEY],
        )
        return b2_api.get_bucket_by_name(entry.data[CONF_BUCKET])

    try:
        bucket = await hass.async_add_executor_job(_authorize_and_get_bucket_sync)
    except exception.Unauthorized as err:
        raise ConfigEntryAuthFailed(
            translation_domain=DOMAIN,
            translation_key="invalid_credentials",
        ) from err
    except exception.RestrictedBucket as err:
        create_bucket_access_restricted_issue(hass, entry, err.bucket_name)
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="restricted_bucket",
            translation_placeholders={
                "restricted_bucket_name": err.bucket_name,
            },
        ) from err
    except exception.NonExistentBucket as err:
        create_bucket_not_found_issue(hass, entry, entry.data[CONF_BUCKET])
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="invalid_bucket_name",
        ) from err
    except exception.BadRequest as err:
        raise ConfigEntryNotReady(
            translation_domain=DOMAIN,
            translation_key="bad_request",
            translation_placeholders={"error_message": str(err)},
        ) from err

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Either reconfigure the integration to use the bucket allowed by the application key, or create a new application key that allows the configured bucket
2. If the bucket was recreated, generate a fresh app key for the new bucket and update credentials
3. Dismiss the repair issue after fixing the mismatch

# before setup: confirm the key can list the target bucket
buckets = [b.name for b in b2_api.list_buckets()]
if entry.data[CONF_BUCKET] not in buckets:
    # restricted or missing: fix key scope or bucket choice now

import b2sdk.v2.exception as b2exc

def is_restricted_bucket(err: BaseException) -> bool:
    return isinstance(err, b2exc.RestrictedBucket)

except exception.RestrictedBucket as err:
    create_bucket_access_restricted_issue(hass, entry, err.bucket_name)
    raise ConfigEntryNotReady(translation_domain=DOMAIN, translation_key="restricted_bucket", ...) from err

When it happens

Trigger: An application key limited via bucketId/bucketName restrictions is used with a CONF_BUCKET entry whose bucket is outside the key's allowed set; b2sdk raises RestrictedBucket with err.bucket_name.

Common situations: User created an app key scoped to bucket A but configured the integration for bucket B; key created with 'Allow access to buckets' left unset; bucket deleted and recreated (new bucketId not covered by the key).

Related errors

• invalid_credentials
• invalid_bucket_name
• bad_request
• invalid_auth
• cannot_connect

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