{"record":{"id":"a67d4f81cc8db9d1","repo":"infiniflow/ragflow","slug":"insufficient-permissions-to-access-bitbucket-works","errorCode":null,"errorMessage":"Insufficient permissions to access Bitbucket workspace (HTTP 403).","messagePattern":"Insufficient permissions to access Bitbucket workspace \\(HTTP 403\\)\\.","errorType":"validation","errorClass":"InsufficientPermissionsError","httpStatus":403,"severity":"error","filePath":"common/data_source/bitbucket/connector.py","lineNumber":301,"sourceCode":"        \"\"\"Validate Bitbucket credentials and workspace access by probing a lightweight endpoint.\n\n        Raises:\n            CredentialExpiredError: on HTTP 401\n            InsufficientPermissionsError: on HTTP 403\n            UnexpectedValidationError: on any other failure\n        \"\"\"\n        try:\n            with self._client() as client:\n                url = f\"https://api.bitbucket.org/2.0/repositories/{self.workspace}\"\n                resp = client.get(\n                    url,\n                    params={\"pagelen\": 1, \"fields\": \"pagelen\"},\n                    timeout=REQUEST_TIMEOUT_SECONDS,\n                )\n                if resp.status_code == 401:\n                    raise CredentialExpiredError(\"Invalid or expired Bitbucket credentials (HTTP 401).\")\n                if resp.status_code == 403:\n                    raise InsufficientPermissionsError(\"Insufficient permissions to access Bitbucket workspace (HTTP 403).\")\n                if resp.status_code < 200 or resp.status_code >= 300:\n                    raise UnexpectedValidationError(f\"Unexpected Bitbucket error (status={resp.status_code}).\")\n        except Exception as e:\n            # Network or other unexpected errors\n            if isinstance(\n                e,\n                (\n                    CredentialExpiredError,\n                    InsufficientPermissionsError,\n                    UnexpectedValidationError,\n                    ConnectorMissingCredentialError,\n                ),\n            ):\n                raise\n            raise UnexpectedValidationError(f\"Unexpected error while validating Bitbucket settings: {e}\")\n\n\nif __name__ == \"__main__\":","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/bitbucket/connector.py#L283-L319","documentation":"HTTP 403 from the workspace repositories endpoint maps to InsufficientPermissionsError: authentication succeeded but the identity cannot list repos in that workspace.","triggerScenarios":"App password lacking the account/repository read scopes, or the authenticated user not being a member (or guest without read) of the target workspace.","commonSituations":"Least-privilege tokens missing 'Repositories: Read'; workspace set to private with team-access restrictions; workspace slug typo pointing at someone else's workspace.","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"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    conn.validate_connector_settings()\nexcept InsufficientPermissionsError as e:\n    guide_user_to_grant_scopes(str(e))  # instruct: app password needs repo read; account needs workspace access\n    raise","preventionTips":["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"],"tags":["bitbucket","http-403","permissions","authorization"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}