infiniflow/ragflow · critical · CredentialExpiredError

Invalid or expired Bitbucket credentials (HTTP 401).

Error message

Invalid or expired Bitbucket credentials (HTTP 401).

What it means

During settings validation, a GET to https://api.bitbucket.org/2.0/repositories/{workspace} returning HTTP 401 maps to CredentialExpiredError: the email/app-password pair was rejected by Bitbucket.

Source

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

    def validate_connector_settings(self) -> None:
        """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}")

View on GitHub (pinned to 554fb1133a)

Solutions

1. Create/confirm an app password in Bitbucket Personal Settings → App passwords with account/repo read scope
2. Update stored bitbucket_api_token and verify bitbucket_email matches the token owner
3. Re-run validate_connector_settings after updating

try:
    conn.validate_connector_settings()
except CredentialExpiredError:
    notify_user_credentials_expired()   # surface re-auth prompt
    creds = refresh_bitbucket_app_password()
    conn.load_credentials(creds)
    conn.validate_connector_settings()

When it happens

Trigger: Revoked or mistyped app password, wrong email (Bitbucket requires the account username/email associated with the token), or a token from a different account.

Common situations: App password regenerated in Bitbucket settings but old value still stored; using the workspace name instead of the account email; SSO-managed accounts with rotated credentials.

Understand the failure class

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

Related errors

• Bitbucket
• GitHub credential appears to be invalid or expired (HTTP 401
• Moodle token is invalid or expired
• main() must be defined or exported.
• Invalid chat_id: ${payload.chat_id}

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