{"record":{"id":"5c912d8e27190324","repo":"infiniflow/ragflow","slug":"failed-to-fetch-mailboxes-status","errorCode":null,"errorMessage":"Failed to fetch mailboxes; {status=}","messagePattern":"Failed to fetch mailboxes; (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"common/data_source/imap_connector.py","lineNumber":386,"sourceCode":"                if not (start_dt < msg_dt <= end_dt):\n                    continue\n\n                slim_doc_batch.append(SlimDocument(id=email_headers.id))\n                for att in extract_attachments(email_msg):\n                    slim_doc_batch.append(SlimDocument(id=_attachment_document_id(email_headers.id, att)))\n\n                if len(slim_doc_batch) >= _PAGE_SIZE:\n                    yield slim_doc_batch\n                    slim_doc_batch = []\n\n        if slim_doc_batch:\n            yield slim_doc_batch\n\n\ndef _fetch_all_mailboxes_for_email_account(mail_client: imaplib.IMAP4_SSL) -> list[str]:\n    status, mailboxes_data = mail_client.list('\"\"', \"*\")\n    if status != _IMAP_OKAY_STATUS:\n        raise RuntimeError(f\"Failed to fetch mailboxes; {status=}\")\n\n    mailboxes = []\n\n    for mailboxes_raw in mailboxes_data:\n        if isinstance(mailboxes_raw, bytes):\n            mailboxes_str = mailboxes_raw.decode()\n        elif isinstance(mailboxes_raw, str):\n            mailboxes_str = mailboxes_raw\n        else:\n            logging.warning(f\"Expected the mailbox data to be of type str, instead got {type(mailboxes_raw)=} {mailboxes_raw}; skipping\")\n            continue\n\n        # The mailbox LIST response output can be found here:\n        # https://www.rfc-editor.org/rfc/rfc3501.html#section-7.2.2\n        #\n        # The general format is:\n        # `(<name-attributes>) <hierarchy-delimiter> <mailbox-name>`\n        #","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/imap_connector.py#L368-L404","documentation":"Raised by _fetch_all_mailboxes_for_email_account when mail_client.list returns a status other than 'OK'. Unlike the empty-result case, the server explicitly reported failure for the LIST command. This usually indicates a session-level problem (dropped connection, unselected state, server-side refusal) rather than missing folders.","triggerScenarios":"The IMAP session timed out or was closed between login and LIST; the server rejects LIST with 'NO' due to ACL or namespace restrictions; a transient server failure mid-sync. Raised as a RuntimeError with the raw status string embedded.","commonSituations":"Long-running sync jobs where the connection idles out; load-shedding or maintenance windows on the mail server; aggressive per-command rate limiting; proxies or middleboxes between client and server.","solutions":["Retry the operation - build a fresh mail client via _get_mail_client() and re-run the checkpoint load.","If persistent, reproduce with a manual LIST (e.g. via Python imaplib) to see the server's exact response and status text.","Check server logs / ACLs if LIST is being denied for this authenticated user.","For long jobs, reduce idle time between login and first command or implement reconnect logic upstream."],"exampleFix":"# before\nmailboxes = _fetch_all_mailboxes_for_email_account(client)  # RuntimeError: status='NO'\n\n# after\nfor attempt in range(3):\n    try:\n        mailboxes = _fetch_all_mailboxes_for_email_account(client)\n        break\n    except RuntimeError:\n        client = connector._get_mail_client()  # fresh session\nelse:\n    raise","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        mailboxes = _fetch_all_mailboxes_for_email_account(client)\n        break\n    except RuntimeError as e:\n        if 'Failed to fetch mailboxes' not in str(e) or attempt == 2:\n            raise\n        time.sleep(2 ** attempt)\n        client = connector._get_mail_client()  # fresh authenticated session","preventionTips":["Always re-login (fresh IMAP4_SSL session) before retrying after a non-OK status.","Keep long sync jobs active or reconnect on a schedule to avoid idle disconnects.","Log the raw status string; IMAP statuses ('NO', 'BYE') distinguish server refusal from disconnect."],"tags":["imap","email","network","retry"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}