{"record":{"id":"bcf34272ed2d2541","repo":"infiniflow/ragflow","slug":"failed-to-find-any-mailboxes-for-this-email-accoun","errorCode":null,"errorMessage":"Failed to find any mailboxes for this email account","messagePattern":"Failed to find any mailboxes for this email account","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"common/data_source/imap_connector.py","lineNumber":240,"sourceCode":"        start: SecondsSinceUnixEpoch,\n        end: SecondsSinceUnixEpoch,\n        checkpoint: ImapCheckpoint,\n        include_perm_sync: bool,\n    ) -> CheckpointOutput[ImapCheckpoint]:\n        checkpoint = cast(ImapCheckpoint, copy.deepcopy(checkpoint))\n        checkpoint.has_more = True\n\n        mail_client = self._get_mail_client()\n\n        if checkpoint.todo_mailboxes is None:\n            # This is the dummy checkpoint.\n            # Fill it with mailboxes first.\n            if self._mailboxes:\n                checkpoint.todo_mailboxes = _sanitize_mailbox_names(self._mailboxes)\n            else:\n                fetched_mailboxes = _fetch_all_mailboxes_for_email_account(mail_client=mail_client)\n                if not fetched_mailboxes:\n                    raise RuntimeError(\"Failed to find any mailboxes for this email account\")\n                checkpoint.todo_mailboxes = _sanitize_mailbox_names(fetched_mailboxes)\n\n            return checkpoint\n\n        if not checkpoint.current_mailbox or not checkpoint.current_mailbox.todo_email_ids:\n            if not checkpoint.todo_mailboxes:\n                checkpoint.has_more = False\n                return checkpoint\n\n            mailbox = checkpoint.todo_mailboxes.pop()\n            email_ids = _fetch_email_ids_in_mailbox(\n                mail_client=mail_client,\n                mailbox=mailbox,\n                start=start,\n                end=end,\n            )\n            checkpoint.current_mailbox = CurrentMailbox(\n                mailbox=mailbox,","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/imap_connector.py#L222-L258","documentation":"Raised during checkpoint initialization when the connector is configured with no explicit mailboxes and the server's LIST command returned zero mailboxes (after sanitization). The connector cannot enumerate anything to sync, so it aborts with a RuntimeError instead of producing an empty, misleadingly successful run.","triggerScenarios":"Running _load_from_checkpoint with self._mailboxes empty and _fetch_all_mailboxes_for_email_account returning an empty list - a brand-new account with no visible folders, an account whose mailboxes are all filtered out by _sanitize_mailbox_names, or a server whose LIST is restricted by ACLs.","commonSituations":"Freshly provisioned mailbox with no folders created; permissions/ACL on the account hiding all folders from LIST; a migration where mail was moved but folder metadata was not; an over-restrictive mailboxes config whose entries were all sanitized away.","solutions":["Check the account in a normal mail client: confirm folders exist and are visible to this user.","Pass an explicit mailbox list when constructing the connector (e.g. mailboxes=['INBOX']) so enumeration is skipped.","If using ACLs, grant the account list/read rights on its own namespaces.","Create at least one folder (or ensure INBOX is enumerable) server-side, then retry."],"exampleFix":"# before\nconnector = ImapConnector(host=..., port=993, credentials=creds, mailboxes=[])\n\n# after\nconnector = ImapConnector(host=..., port=993, credentials=creds, mailboxes=['INBOX'])","handlingStrategy":"validation","validationCode":"def imap_has_enumerable_mailboxes(connector, client) -> bool:\n    if connector._mailboxes:\n        return True\n    return bool(client.list('\"\"', '*')[1])","typeGuard":null,"tryCatchPattern":"try:\n    output = connector.load_from_checkpoint(start, end, checkpoint)\nexcept RuntimeError as e:\n    if 'Failed to find any mailboxes' in str(e):\n        log.warning('Account has no visible folders; configure explicit mailboxes')\n        raise\n    raise","preventionTips":["Configure explicit mailboxes=['INBOX'] for accounts whose LIST may be restricted.","Verify folder visibility with a real mail client as part of account onboarding.","Do not treat an empty mailbox set as a successful no-op sync."],"tags":["imap","email","mailbox","connector"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}