{"record":{"id":"43a2d69687d07d4a","repo":"infiniflow/ragflow","slug":"failed-to-log-into-imap-server-status","errorCode":null,"errorMessage":"Failed to log into imap server; {status=}","messagePattern":"Failed to log into imap server; (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"common/data_source/imap_connector.py","lineNumber":216,"sourceCode":"        This function will throw an error if the credentials have not yet been set.\n        \"\"\"\n\n        def get_or_raise(name: str) -> str:\n            value = self.credentials.get(name)\n            if not value:\n                raise RuntimeError(f\"Credential item {name=} was not found\")\n            if not isinstance(value, str):\n                raise RuntimeError(f\"Credential item {name=} must be of type str, instead received {type(name)=}\")\n            return value\n\n        username = get_or_raise(_USERNAME_KEY)\n        password = get_or_raise(_PASSWORD_KEY)\n\n        mail_client = imaplib.IMAP4_SSL(host=self._host, port=self._port)\n        status, _data = mail_client.login(user=username, password=password)\n\n        if status != _IMAP_OKAY_STATUS:\n            raise RuntimeError(f\"Failed to log into imap server; {status=}\")\n\n        return mail_client\n\n    def _load_from_checkpoint(\n        self,\n        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.","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/data_source/imap_connector.py#L198-L234","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the username/password pair with a manual client (e.g. a small imaplib script or Thunderbird) against the same host/port.","For Gmail/Workspace, generate an app password (or enable IMAP in account settings) and use it as the password.","Confirm host/port: imap.gmail.com:993, outlook.office365.com:993, etc., and that the account permits IMAP.","If the account may be locked, check with the mail admin and unlock before retrying."],"exampleFix":"# before\ncreds = {'username': 'user@example.com', 'password': 'regular-account-password'}  # Gmail -> status 'NO'\n\n# after\ncreds = {'username': 'user@example.com', 'password': os.environ['GMAIL_APP_PASSWORD']}  # 16-char app password","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    client = connector._get_mail_client()\nexcept RuntimeError as e:\n    if 'Failed to log into imap server' in str(e):\n        mark_credentials_invalid(user_id)  # surface to user, do not retry blindly\n        raise\n    raise","preventionTips":["Use app passwords or OAuth-capable providers for Gmail and Microsoft accounts.","Pre-test credentials with a lightweight login probe before scheduling long sync jobs.","Rotate credentials through a single store so all workers see updates at once."],"tags":["imap","email","authentication","network"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}