xtekky/gpt4free · error · RuntimeError

OAuth callback timed out

Error message

OAuth callback timed out

What it means

In the local-callback login flow, the provider starts a localhost HTTP server and blocks in wait_for_callback(); this error fires when that call returns a falsy result — no callback request ever arrived and the wait mechanism gave up. The browser never hit the redirect URI on the local port.

Source

Thrown at g4f/Provider/needs_auth/Antigravity.py:856

                print("Please open the URL above manually.\n")
        else:
            if not server_started:
                print(
                    f"\nCould not start local callback server on port {OAUTH_CALLBACK_PORT}."
                )
                print("You may need to close any application using that port.\n")

            print(f"\nPlease open this URL in your browser:\n")
            print(f"{auth_url}\n")

        if server_started:
            print("Waiting for authentication callback...")

            try:
                callback_result = callback_server.wait_for_callback()

                if not callback_result:
                    raise RuntimeError("OAuth callback timed out")

                code = callback_result.get("code")
                callback_state = callback_result.get("state")

                if not code:
                    raise RuntimeError("No authorization code received")

                print("\n✓ Authorization code received. Exchanging for tokens...")

                # Exchange code for tokens
                tokens = await cls.exchange_code_for_tokens(
                    code, callback_state or state
                )

                print(f"✓ Authentication successful!")
                if tokens.get("email"):
                    print(f"  Logged in as: {tokens['email']}")
                if tokens.get("project_id"):

View on GitHub (pinned to 973504e177)

Solutions

1. Free the local port (kill the process holding it) or let the provider pick another, then restart login.
2. On remote/headless machines, set up an SSH tunnel for the callback port and open the URL in your local browser, or use the manual paste flow instead.
3. Open the printed authorization URL in a browser on the same machine and complete consent.

import socket

def callback_port_free(port: int) -> bool:
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        return s.connect_ex(("127.0.0.1", port)) != 0

try:
    tokens = await Antigravity.login()
except RuntimeError as e:
    if "OAuth callback timed out" in str(e):
        # free the port / fix port-forwarding, then restart login
        raise

When it happens

Trigger: wait_for_callback() returns None/empty because the OS browser could not reach http://localhost:<port>/callback: port occupied by another process, browser opened on a different machine (SSH/remote session), firewall blocking loopback listeners, or user never completed consent.

Common situations: Running the login flow inside a container/remote server where the printed URL must be opened and port-forwarded manually; port already bound by a previous crashed attempt; headless environments without a browser.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• OAuth error: {OAuthCallbackHandler.callback_error}
• No authorization code received
• Could not extract authorization code
• OAuth callback timed out
• Failed to read OAuth credentials from {path}: {e}

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/0bbd774c809689e4. Report an issue: GitHub.