infiniflow/ragflow · error · InsufficientPermissionsError

Insufficient permissions to access Bitbucket workspace (HTTP

Error message

Insufficient permissions to access Bitbucket workspace (HTTP 403).

What it means

HTTP 403 from the workspace repositories endpoint maps to InsufficientPermissionsError: authentication succeeded but the identity cannot list repos in that workspace.

Source

Thrown at common/data_source/bitbucket/connector.py:301

        """Validate Bitbucket credentials and workspace access by probing a lightweight endpoint.

        Raises:
            CredentialExpiredError: on HTTP 401
            InsufficientPermissionsError: on HTTP 403
            UnexpectedValidationError: on any other failure
        """
        try:
            with self._client() as client:
                url = f"https://api.bitbucket.org/2.0/repositories/{self.workspace}"
                resp = client.get(
                    url,
                    params={"pagelen": 1, "fields": "pagelen"},
                    timeout=REQUEST_TIMEOUT_SECONDS,
                )
                if resp.status_code == 401:
                    raise CredentialExpiredError("Invalid or expired Bitbucket credentials (HTTP 401).")
                if resp.status_code == 403:
                    raise InsufficientPermissionsError("Insufficient permissions to access Bitbucket workspace (HTTP 403).")
                if resp.status_code < 200 or resp.status_code >= 300:
                    raise UnexpectedValidationError(f"Unexpected Bitbucket error (status={resp.status_code}).")
        except Exception as e:
            # Network or other unexpected errors
            if isinstance(
                e,
                (
                    CredentialExpiredError,
                    InsufficientPermissionsError,
                    UnexpectedValidationError,
                    ConnectorMissingCredentialError,
                ),
            ):
                raise
            raise UnexpectedValidationError(f"Unexpected error while validating Bitbucket settings: {e}")


if __name__ == "__main__":

View on GitHub (pinned to 554fb1133a)

Solutions

Edit the app password to include repository read scope (and snippet/issue scopes if those resources are used)
Confirm the account has at least read access to the workspace
Verify self.workspace is the correct slug from the Bitbucket URL

Defensive patterns

Strategy: try-catch

Try / catch

try:
    conn.validate_connector_settings()
except InsufficientPermissionsError as e:
    guide_user_to_grant_scopes(str(e))  # instruct: app password needs repo read; account needs workspace access
    raise

Prevention

Request app passwords with the minimum scopes you actually use (Repositories: Read at minimum)
Verify the account's workspace membership during onboarding
Document required scopes next to the credential form

When it happens

Trigger: App password lacking the account/repository read scopes, or the authenticated user not being a member (or guest without read) of the target workspace.

Common situations: Least-privilege tokens missing 'Repositories: Read'; workspace set to private with team-access restrictions; workspace slug typo pointing at someone else's workspace.

Understand the failure class

HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

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