FastAPI POST scalar parameter binds as query, ignoring JSON body, causing device-code flow CLI to hang
Device-code login polled forever: FastAPI scalar POST param binds as query, silently ignoring the client's JSON body. A CLI's browser device-code login never completed: the user authorized in the browser (server created the agent key and flipped the record to authorized), but the polling CLI never picked the key up and printed dots indefinitely. Reproduced across multiple fresh codes; shipped for ~3 months in every released CLI version without detection.
Root cause is a two-sided wire-format mismatch:
- Server:
async def device_poll(request: Request, device_code: str = "")— in FastAPI a scalar parameter with a default on a POST route binds as a QUERY parameter. A JSON body is silently ignored, sodevice_codewas always empty and the endpoint returned 400. - Client: polled with
httpx.post(url, json={"device_code": ...}), and its retry loop treated every non-2xx as transient (if not resp.is_success: continue), so the 400 never surfaced — just infinite polling.
Why tests never caught it: the only server test for the endpoint polled with params= (the server author's assumed format), never the JSON-body shape the shipped client actually sends.
Fix both sides, in this order:
- Server (high leverage — heals every already-shipped client on deploy, no upgrade needed): before the empty-param 400 guard, fall back to the body:
if not device_code: body = await request.json(); device_code = str(body.get("device_code") or "")(wrapped in try/except). Reading the body manually instead of adding a Pydantic Body param keeps the OpenAPI spec unchanged, avoiding SDK regeneration churn. - Client: send the format the contract declares (query string), and make non-5xx/429 poll responses terminal instead of
continue— silent retry on 4xx is what hid this for months. - Regression test that posts the EXACT wire shape the shipped client sends (JSON body), not just the shape the server author intended. Any endpoint with both an in-repo client and hand-rolled HTTP calls deserves one test per real caller format.
General rule: in FastAPI, a scalar param with a default on a POST is a query param; if you meant body, use a Pydantic model or Body(...). Clients sending JSON bodies to such endpoints fail with 400/422, and lenient retry loops convert that into an infinite hang.