{"record":{"id":"a051eccb51b90ff1","repo":"infiniflow/ragflow","slug":"unexpected-error-during-box-settings-validation","errorCode":null,"errorMessage":"Unexpected error during Box settings validation: {e}","messagePattern":"Unexpected error during Box settings validation: (.+?)","errorType":"validation","errorClass":"ConnectorValidationError","httpStatus":null,"severity":"error","filePath":"common/data_source/box_connector.py","lineNumber":37,"sourceCode":"    def __init__(self, folder_id: str, batch_size: int = INDEX_BATCH_SIZE, use_marker: bool = True) -> None:\n        self.batch_size = batch_size\n        self.folder_id = \"0\" if not folder_id else folder_id\n        self.use_marker = use_marker\n        self.box_client: BoxClient | None = None\n\n    def load_credentials(self, auth: Any):\n        self.box_client = BoxClient(auth=auth)\n        return None\n\n    def validate_connector_settings(self):\n        if self.box_client is None:\n            raise ConnectorMissingCredentialError(\"Box\")\n\n        try:\n            self.box_client.users.get_user_me()\n        except Exception as e:\n            logging.exception(\"[Box]: Failed to validate Box credentials\")\n            raise ConnectorValidationError(f\"Unexpected error during Box settings validation: {e}\")\n\n    def _iter_files_recursive(\n        self,\n        folder_id: str,\n        relative_folder_path: str = \"\",\n    ) -> Generator[tuple[Any, str], None, None]:\n        if self.box_client is None:\n            raise ConnectorMissingCredentialError(\"Box\")\n\n        result = self.box_client.folders.get_folder_items(\n            folder_id=folder_id,\n            limit=self.batch_size,\n            usemarker=self.use_marker,\n        )\n\n        while True:\n            for entry in result.entries:\n                if entry.type == \"file\":","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/box_connector.py#L19-L55","documentation":"Raised by BoxConnector.validate_connector_settings as the generic failure branch: the credential probe self.box_client.users.get_user_me() threw an exception, so the connector wraps it in ConnectorValidationError('Unexpected error during Box settings validation: {e}'). The original exception is also logged via logging.exception with tag '[Box]', so the stack trace with the real cause is in the logs. Any Box API error — auth failure, network error, permission restriction — lands here.","triggerScenarios":"get_user_me() failing: expired/invalid OAuth access token (invalid_request/expired_token), CCG/JWT misconfiguration (wrong enterprise id, bad private key, unauthorized app), network unreachable to api.box.com, or the Box app's access level restricting the users scope.","commonSituations":"OAuth access token expired and no refresh flow wired up (Box tokens last 60 minutes); CCG auth with enterprise_id unset; Box Platform app not authorized for the enterprise; corporate firewall blocking api.box.com; JWT keypair regenerated in the Box console but the old key still configured.","solutions":["Check the logged '[Box]: Failed to validate Box credentials' exception — it contains the exact Box error (expired token, invalid client credentials, forbidden, etc.)","If OAuth: ensure the auth object refreshes tokens (refresh token present) and the app still has grant access for the user","If CCG/JWT: verify client_id, client_secret, enterprise_id, and the private key match the current Box console values","Confirm network access to https://api.box.com from the indexing host"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"try:\n    me = connector.box_client.users.get_user_me()\nexcept Exception as e:\n    log.exception('Box probe failed: %s', e)  # inspect real cause before wrapping\n    raise\nconnector.validate_connector_settings()","typeGuard":null,"tryCatchPattern":"from common.data_source.exceptions import ConnectorValidationError\ntry:\n    connector.validate_connector_settings()\nexcept ConnectorValidationError as e:\n    cause = str(e)\n    if 'invalid_grant' in cause or 'expired' in cause.lower():\n        refresh_oauth_token_and_retry()\n    elif 'Forbidden' in cause or 'access_denied' in cause:\n        alert_ops('Box app not authorized for this enterprise')\n    else:\n        raise","preventionTips":["Keep the '[Box]: Failed to validate Box credentials' log line searchable — the wrapped message alone hides the Box error kind","For CCG, re-verify enterprise_id/client_secret after any Box app re-authorization; for OAuth, wire token refresh before running validation"],"tags":["box","authentication","oauth","validation"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}