infiniflow/ragflow · error · RuntimeError

Failed to log into imap server; {status=}

Error message

Failed to log into imap server; {status=}

What it means

Raised when imaplib.IMAP4_SSL.login() returns a status other than 'OK'. Note that imaplib usually raises IMAP4.error itself for login failures; this guard catches servers that answer with a non-OK status (e.g. 'NO') without raising, so a failed authentication still aborts cleanly. It fires only after a TLS connection to the IMAP host was already established.

Source

Thrown at common/data_source/imap_connector.py:216

        This function will throw an error if the credentials have not yet been set.
        """

        def get_or_raise(name: str) -> str:
            value = self.credentials.get(name)
            if not value:
                raise RuntimeError(f"Credential item {name=} was not found")
            if not isinstance(value, str):
                raise RuntimeError(f"Credential item {name=} must be of type str, instead received {type(name)=}")
            return value

        username = get_or_raise(_USERNAME_KEY)
        password = get_or_raise(_PASSWORD_KEY)

        mail_client = imaplib.IMAP4_SSL(host=self._host, port=self._port)
        status, _data = mail_client.login(user=username, password=password)

        if status != _IMAP_OKAY_STATUS:
            raise RuntimeError(f"Failed to log into imap server; {status=}")

        return mail_client

    def _load_from_checkpoint(
        self,
        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.

View on GitHub (pinned to 554fb1133a)

Solutions

1. Verify the username/password pair with a manual client (e.g. a small imaplib script or Thunderbird) against the same host/port.
2. For Gmail/Workspace, generate an app password (or enable IMAP in account settings) and use it as the password.
3. Confirm host/port: imap.gmail.com:993, outlook.office365.com:993, etc., and that the account permits IMAP.
4. If the account may be locked, check with the mail admin and unlock before retrying.

Example fix

# before
creds = {'username': 'user@example.com', 'password': 'regular-account-password'}  # Gmail -> status 'NO'

# after
creds = {'username': 'user@example.com', 'password': os.environ['GMAIL_APP_PASSWORD']}  # 16-char app password

try:
    client = connector._get_mail_client()
except RuntimeError as e:
    if 'Failed to log into imap server' in str(e):
        mark_credentials_invalid(user_id)  # surface to user, do not retry blindly
        raise
    raise

When it happens

Trigger: Wrong password or username against the given host; account locked or IMAP disabled; Gmail/Office365 without an app password or without IMAP enabled; connecting to the wrong host/port so the server rejects the user.

Common situations: Gmail requiring app passwords after password-login deprecation; Microsoft disabling basic auth; corporate IMAP gateways with lockout after failed attempts; credential rotation that only updated some deployments.

Related errors

• Failed to fetch mailboxes; {status=}
• Failed to fetch email ids; {status=}
• Failed to connect to SSH host {self.username}@{self.host}:{s
• BigQuery validation failed: {exc}
• Credential item {name=} was not found

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