infiniflow/ragflow · error · RuntimeError

Failed to find any mailboxes for this email account

Error message

Failed to find any mailboxes for this email account

What it means

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.

Source

Thrown at common/data_source/imap_connector.py:240

        start: SecondsSinceUnixEpoch,
        end: SecondsSinceUnixEpoch,
        checkpoint: ImapCheckpoint,
        include_perm_sync: bool,
    ) -> CheckpointOutput[ImapCheckpoint]:
        checkpoint = cast(ImapCheckpoint, copy.deepcopy(checkpoint))
        checkpoint.has_more = True

        mail_client = self._get_mail_client()

        if checkpoint.todo_mailboxes is None:
            # This is the dummy checkpoint.
            # Fill it with mailboxes first.
            if self._mailboxes:
                checkpoint.todo_mailboxes = _sanitize_mailbox_names(self._mailboxes)
            else:
                fetched_mailboxes = _fetch_all_mailboxes_for_email_account(mail_client=mail_client)
                if not fetched_mailboxes:
                    raise RuntimeError("Failed to find any mailboxes for this email account")
                checkpoint.todo_mailboxes = _sanitize_mailbox_names(fetched_mailboxes)

            return checkpoint

        if not checkpoint.current_mailbox or not checkpoint.current_mailbox.todo_email_ids:
            if not checkpoint.todo_mailboxes:
                checkpoint.has_more = False
                return checkpoint

            mailbox = checkpoint.todo_mailboxes.pop()
            email_ids = _fetch_email_ids_in_mailbox(
                mail_client=mail_client,
                mailbox=mailbox,
                start=start,
                end=end,
            )
            checkpoint.current_mailbox = CurrentMailbox(
                mailbox=mailbox,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Check the account in a normal mail client: confirm folders exist and are visible to this user.
2. Pass an explicit mailbox list when constructing the connector (e.g. mailboxes=['INBOX']) so enumeration is skipped.
3. If using ACLs, grant the account list/read rights on its own namespaces.
4. Create at least one folder (or ensure INBOX is enumerable) server-side, then retry.

Example fix

# before
connector = ImapConnector(host=..., port=993, credentials=creds, mailboxes=[])

# after
connector = ImapConnector(host=..., port=993, credentials=creds, mailboxes=['INBOX'])

def imap_has_enumerable_mailboxes(connector, client) -> bool:
    if connector._mailboxes:
        return True
    return bool(client.list('""', '*')[1])

try:
    output = connector.load_from_checkpoint(start, end, checkpoint)
except RuntimeError as e:
    if 'Failed to find any mailboxes' in str(e):
        log.warning('Account has no visible folders; configure explicit mailboxes')
        raise
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Credential item {name=} was not found
• Credential item {name=} must be of type str, instead receive
• Failed to log into imap server; {status=}
• Failed to fetch mailboxes; {status=}
• Failed to fetch email ids; {status=}

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