odysseus-dev/odysseus · error · RuntimeError

Google OAuth token unavailable — reconnect the account

Error message

Google OAuth token unavailable — reconnect the account

What it means

Error "Google OAuth token unavailable — reconnect the account" thrown in odysseus-dev/odysseus.

Source

Thrown at routes/email_routes.py:5867

        imap_pass = body.get("imap_password") or ""
        imap_starttls = bool(body.get("imap_starttls"))
        oauth_provider = body.get("oauth_provider") or ""

        google_token = None
        google_token_loaded = False
        google_ssl_context = (
            ssl.create_default_context()
            if oauth_provider == "google"
            else None
        )

        def _google_token():
            nonlocal google_token, google_token_loaded
            if not google_token_loaded:
                google_token = _get_valid_google_token(body.get("account_id"), body)
                google_token_loaded = True
            if not google_token:
                raise RuntimeError("Google OAuth token unavailable — reconnect the account")
            return google_token

        if imap_port_err:
            imap_result = {"ok": False, "error": imap_port_err}
        elif not (imap_host and imap_user and (imap_pass or oauth_provider == "google")):
            imap_result = {"ok": False, "error": "Need IMAP host, username, and password"}
        elif oauth_provider == "google" and _normalized_mail_host(imap_host) != _GOOGLE_OAUTH_IMAP_HOST:
            imap_result = {"ok": False, "error": "Google OAuth IMAP requires imap.gmail.com"}
        elif oauth_provider == "google" and not _google_oauth_imap_transport_allowed(imap_port, imap_starttls):
            imap_result = {"ok": False, "error": "Google OAuth IMAP requires TLS on port 993 or STARTTLS on port 143"}
        else:
            # Connection mode resolution:
            #   STARTTLS on  → plain IMAP4 + .starttls() (upgrade)
            #   STARTTLS off + port 993 → IMAP4_SSL (implicit SSL, "IMAPS")
            #   STARTTLS off + any other port → plain IMAP4 (no encryption)
            # Without the last branch, local servers exposed on a non-993
            # port (Dovecot on 31143, etc.) would always fail the SSL
            # handshake because they're not actually wrapped in TLS.

View on GitHub (pinned to f9235ebbf1)

Solutions

1. Reconnect the Google account in Settings → Integrations to refresh the OAuth token.
2. Check that Google OAuth credentials are still valid and scopes include mail access.

When it happens

Trigger: Triggered when the corresponding server-side validation or runtime check at the recorded location rejects the request or operation and returns this error message to the caller.

Common situations: See trigger scenarios.

AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14). Data as JSON: /api/errors/bb424a8ba9f6e555. Report an issue: GitHub.