infiniflow/ragflow · error · UnexpectedValidationError

Unexpected Bitbucket error (status={resp.status_code}).

Error message

Unexpected Bitbucket error (status={resp.status_code}).

What it means

Any non-2xx response other than 401/403 from the workspace endpoint is wrapped as UnexpectedValidationError with the raw status code — e.g. 404 (bad workspace slug), 429 (rate limit).

Source

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

        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__":
    bitbucket = BitbucketConnector(workspace="<YOUR_WORKSPACE>")

View on GitHub (pinned to 554fb1133a)

Solutions

1. Inspect the status in the message; 404 → fix the workspace slug, 429 → back off and retry with jitter, 5xx → retry later
2. Cache workspace existence checks to avoid repeated lookups
3. Add exponential backoff around paginated calls

# Pre-check workspace existence cheaply
resp = client.get(f"https://api.bitbucket.org/2.0/repositories/{workspace}", params={"pagelen": 1})
if resp.status_code == 404:
    raise ValueError(f"workspace '{workspace}' does not exist")

import time, random
for attempt in range(5):
    try:
        conn.validate_connector_settings(); break
    except UnexpectedValidationError as e:
        if "status=429" in str(e) or "status=5" in str(e):
            time.sleep((2 ** attempt) + random.random())  # backoff and retry
        else:
            raise  # 404 etc. need a config fix, not a retry

When it happens

Trigger: GET /2.0/repositories/{workspace}?pagelen=1 returning 404 for a nonexistent workspace, 429 when rate-limited, or 5xx during Bitbucket outages.

Common situations: Typo'd workspace slug; scripts hammering the API without backoff; transient Bitbucket 5xx pages.

Related errors

• main() returned a non-JSON-serializable value.
• Failed to fetch skills
• API rate limit exceeded. ${limit} requests/hour for unauthen
• Repository or path not found. Please check the URL and ensur
• User '{username}' not found

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