infiniflow/ragflow · error · InsufficientPermissionsError

Your Dropbox token does not have sufficient permissions.

Error message

Your Dropbox token does not have sufficient permissions.

What it means

Raised by validate_connector_settings() when files_list_folder throws an ApiError whose string contains 'insufficient_permissions'. The token authenticates but lacks the OAuth scope (files.metadata.read) or team-level permission needed to list the root folder. Mapped to InsufficientPermissionsError so the caller can surface an authorization rather than authentication problem.

Source

Thrown at common/data_source/dropbox_connector.py:52

        if not access_token:
            raise ConnectorMissingCredentialError("Dropbox access token is required")

        self.dropbox_client = Dropbox(access_token)
        return None

    def validate_connector_settings(self) -> None:
        """Validate Dropbox connector settings"""
        if self.dropbox_client is None:
            raise ConnectorMissingCredentialError("Dropbox")

        try:
            self.dropbox_client.files_list_folder(path="", limit=1)
        except AuthError as e:
            logger.exception("[Dropbox]: Failed to validate Dropbox credentials")
            raise ConnectorValidationError(f"Dropbox credential is invalid: {e}")
        except ApiError as e:
            if e.error is not None and "insufficient_permissions" in str(e.error).lower():
                raise InsufficientPermissionsError("Your Dropbox token does not have sufficient permissions.")
            raise ConnectorValidationError(f"Unexpected Dropbox error during validation: {e.user_message_text or e}")
        except Exception as e:
            raise ConnectorValidationError(f"Unexpected error during Dropbox settings validation: {e}")

    def _download_file(self, path: str) -> bytes:
        """Download a single file from Dropbox."""
        if self.dropbox_client is None:
            raise ConnectorMissingCredentialError("Dropbox")
        _, resp = self.dropbox_client.files_download(path)
        return resp.content

    def _get_shared_link(self, path: str) -> str:
        """Create a shared link for a file in Dropbox."""
        if self.dropbox_client is None:
            raise ConnectorMissingCredentialError("Dropbox")

        try:
            shared_links = self.dropbox_client.sharing_list_shared_links(path=path)

View on GitHub (pinned to 554fb1133a)

Solutions

In the Dropbox App Console Permissions tab, grant files.metadata.read (and files.content.read/sharing.read for indexing), then generate a NEW token — scope changes do not apply to existing tokens
Confirm the app has production status if it needs broader access
Team admins: verify the app is allow-listed under team API/permission policies

Defensive patterns

Strategy: try-catch

Try / catch

try:
    connector.validate_connector_settings()
except InsufficientPermissionsError:
    notify_user('Dropbox token lacks required scopes; grant them in the App Console and generate a NEW token')

Prevention

Select all needed scopes BEFORE generating a token — scope edits do not affect existing tokens
Prefer short-lived tokens generated via OAuth code flow so scope changes apply on next authorization

When it happens

Trigger: Scoped-access token created without files.metadata.read; team member token restricted by team policies; app in development status requesting scopes beyond its allowed set.

Common situations: Token generated before scopes were selected in the App Console; team admins restricting third-party apps; scope set trimmed during token rotation.

Related errors

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