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.

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.

Appendix: 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)