infiniflow/ragflow · error · InsufficientPermissionsError

Azure Blob: insufficient permissions on container: {msg[:300

Error message

Azure Blob: insufficient permissions on container: {msg[:300]}

What it means

Raised by validate_connector_settings when get_container_properties() returns an authorization failure that is not an authentication failure — the credential is valid but lacks permission on this container. Azure's 'AuthorizationPermissionMismatch' or any 403 without the auth-failed signature maps to InsufficientPermissionsError.

Source

Thrown at common/data_source/azure_blob_connector.py:193

    # Validation
    # ------------------------------------------------------------------

    def validate_connector_settings(self) -> None:
        if self._container_client is None:
            raise ConnectorMissingCredentialError("Azure Blob")

        try:
            # get_container_properties() costs one API call; it returns
            # the ETag and last-modified of the container, proving both
            # the credential and the container name are valid.
            self._container_client.get_container_properties()
        except Exception as exc:
            msg = str(exc)
            code = getattr(getattr(exc, "error_code", None), "value", None) or getattr(exc, "error_code", "")
            if "AuthenticationFailed" in msg or "InvalidAuthenticationInfo" in msg:
                raise ConnectorMissingCredentialError(f"Azure Blob credential rejected: {msg[:300]}") from exc
            if "AuthorizationPermissionMismatch" in msg or "403" in msg:
                raise InsufficientPermissionsError(f"Azure Blob: insufficient permissions on container: {msg[:300]}") from exc
            if "ContainerNotFound" in msg or "404" in msg:
                raise ConnectorValidationError(f"Azure Blob: container not found: {msg[:300]}") from exc
            raise UnexpectedValidationError(f"Azure Blob validation failed ({code}): {msg[:300]}") from exc

    # ------------------------------------------------------------------
    # Checkpoint helpers
    # ------------------------------------------------------------------

    def build_dummy_checkpoint(self) -> AzureBlobCheckpoint:
        return AzureBlobCheckpoint(has_more=True)

    def validate_checkpoint_json(self, checkpoint_json: str) -> AzureBlobCheckpoint:
        try:
            return AzureBlobCheckpoint.model_validate_json(checkpoint_json)
        except Exception:
            return self.build_dummy_checkpoint()

    # ------------------------------------------------------------------

View on GitHub (pinned to 554fb1133a)

Solutions

1. For SAS: reissue the token with read + list permissions at container scope
2. For service-principal/account-key setups: grant 'Storage Blob Data Reader' (or Contributor) at the storage account or container scope and wait for RBAC propagation (can take minutes)
3. Verify the error body (included, truncated to 300 chars) confirms AuthorizationPermissionMismatch rather than AuthenticationFailed — the fix differs

# Nothing local can prove RBAC; a dry-run listing is the practical pre-check:
try:
    client.get_container_properties()
except Exception as e:
    if "AuthorizationPermissionMismatch" in str(e):
        raise PermissionError("grant Storage Blob Data Reader before ingest") from e

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError as e:
    # credential valid but under-privileged: alert infra owner, don't retry
    alert_ops(f"Azure RBAC missing for connector: {e}")
    raise

When it happens

Trigger: Account key or SAS token authenticates correctly but has no RBAC role / SAS permission to read container properties: e.g. a service principal with no 'Storage Blob Data Reader' role, or a SAS token lacking the List permission (container-level read of properties requires appropriate scope).

Common situations: Least-privilege SAS tokens issued without the 'container' permission bit, service principals granted roles at the wrong scope (subscription instead of the storage account/container), or Azure RBAC propagation delay after a role assignment.

Related errors

• main() must return a value. Use null for an empty result.
• not implement: show role {role_name}
• not implement: grant role {role_name} actions: {actions} on
• not implement: revoke role {role_name} actions: {actions} on
• not implement: get user permission: {user_name}

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/07012834930fb5a3. Report an issue: GitHub.