infiniflow/ragflow · error · InsufficientPermissionsError

Insufficient permissions to access Confluence resources (HTT

Error message

Insufficient permissions to access Confluence resources (HTTP 403).

What it means

Raised by validate_connector_settings() when the get_all_spaces probe returns HTTP 403. The credentials authenticate correctly but the account/integration lacks permission to list spaces (missing 'View space' / read scope, OAuth client scopes not granted, or GAC restrictions). Mapped to InsufficientPermissionsError so the UI can distinguish authorization failure from authentication failure.

Source

Thrown at common/data_source/confluence_connector.py:1844

                yield doc_metadata_list[:_SLIM_DOC_BATCH_SIZE]
                doc_metadata_list = doc_metadata_list[_SLIM_DOC_BATCH_SIZE:]

                if callback and callback.should_stop():
                    raise RuntimeError("retrieve_all_slim_docs_perm_sync: Stop signal detected")
                if callback:
                    callback.progress("retrieve_all_slim_docs_perm_sync", 1)

        yield doc_metadata_list

    def validate_connector_settings(self) -> None:
        try:
            spaces = self.low_timeout_confluence_client.get_all_spaces(limit=1)
        except HTTPError as e:
            status_code = e.response.status_code if e.response else None
            if status_code == 401:
                raise CredentialExpiredError("Invalid or expired Confluence credentials (HTTP 401).")
            elif status_code == 403:
                raise InsufficientPermissionsError("Insufficient permissions to access Confluence resources (HTTP 403).")
            raise UnexpectedValidationError(f"Unexpected Confluence error (status={status_code}): {e}")
        except Exception as e:
            raise UnexpectedValidationError(f"Unexpected error while validating Confluence settings: {e}")

        if self.space:
            try:
                self.low_timeout_confluence_client.get_space(self.space)
            except ApiError as e:
                raise ConnectorValidationError("Invalid Confluence space key provided") from e

        if not spaces or not spaces.get("results"):
            raise ConnectorValidationError("No Confluence spaces found. Either your credentials lack permissions, or there truly are no spaces in this Confluence instance.")


if __name__ == "__main__":
    import os

    # base url

View on GitHub (pinned to 554fb1133a)

Solutions

1. Grant the account/integration read access to the target spaces (space settings > permissions, or Confluence admin > global permissions)
2. For scoped tokens, add the read:confluence-space / search scopes when creating the token
3. For 3LO apps, add the required OAuth scopes and re-consent
4. Test with the same account in the Confluence UI: can it see the space browser?

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError:
    notify_user('Grant the Confluence integration read access to spaces, then revalidate')

When it happens

Trigger: Valid API token whose account has no space-level read permission; an OAuth 2.0 (3LO) app missing read:confluence-space scope; Confluence Cloud where every space restricts access from the integration.

Common situations: New service account added without group membership; admin granted token but forgot space permissions; scoped tokens (scoped_token param) missing the space list scope.

Understand the failure class

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

Related errors

• The calling user does not have permission
• main() must return a value. Use null for an empty result.
• Insufficient permissions to access Bitbucket workspace (HTTP
• Insufficient permissions to list objects in bucket '{self.bu
• Invalid or expired Confluence credentials (HTTP 401).

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