What the agent does
websockets 14.0, released in November 2024, made its new asyncio implementation the default behind websockets.serve. Up to 13.1 that name pointed at websockets.legacy.server, which called a connection handler with two arguments, the connection and the request path. From 14.0 it points at websockets.asyncio.server, which calls the handler with the connection alone. A server written for 10.x then logs connection handler failed and TypeError: handle_websocket() missing 1 required positional argument: 'path' for every connection, and the client sees the socket close with code 1011. The connection object changed too: websocket.request_headers is gone, and the request's headers and path live on websocket.request.
hsadler/unity-websocket-multiplayer, a Unity game client with a Python game server, shows both breaks in one file. PythonGameServer/requirements.txt pins websockets==10.0, the Dockerfile builds on python:3.10-alpine and installs it, and docker-compose.yaml runs python server.py on port 5000. server.py defines async def handle_websocket(websocket, path) and starts it from main() with async with websockets.serve(handle_websocket, host="0.0.0.0", port=5000, logger=LoggerAdapter(...)), where the adapter's process method reads websocket.request_headers.get("X-Forwarded-For") to prefix log lines with the client address. It broadcasts with websockets.broadcast(game_state.connections, ...), which exists on both implementations. The pin keeps this working; the day someone bumps it past 14, or installs the server without the pin, both lines fail.
The agent reproduces on a clean environment with the current release, 17.4, and takes the breaks in the order they happen. With the adapter in place the first failure is inside logging, AttributeError: 'ServerConnection' object has no attribute 'request_headers', raised while the server tries to log the handshake, so the client never gets a valid HTTP response. With that line changed to websocket.request.headers.get("X-Forwarded-For") the handshake completes and the second failure appears: connection handler failed with the TypeError above, and the client closed with 1011. The handler signature becomes async def handle_websocket(websocket); a server that used path reads websocket.request.path instead.
Then it proves the server works by being a client. It starts server.py, connects with websockets.connect, reads the SERVER_MESSAGE_TYPE_GAME_STATE message the handler sends on connect, sends a CLIENT_MESSAGE_TYPE_PLAYER_ENTER message with a player id and position, and reads the SERVER_MESSAGE_TYPE_PLAYER_ENTER broadcast that comes back, with the server log showing player entered and no traceback. It moves the pin to the release it tested against and leaves the Dockerfile, the Unity client and the message format alone.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This websocket server fails with \"TypeError: handler() missing 1 required positional argument: 'path'\" after the websockets package was upgraded. Read the dependency files and report the pinned version, then create a clean virtual environment on a current Python, install the current websockets release, and report the version that was resolved. Start the server and connect to it with a small client; save every traceback the server logs, in the order they appear, and the close code the client sees. Find every connection handler passed to websockets.serve and list each with its file, line and signature. Change two-argument handlers to take the connection only, and read the request path from websocket.request.path where the old path argument was used. Replace websocket.request_headers with websocket.request.headers. Do not add a version pin below 14 to keep the legacy implementation. Start the server again, connect, exchange at least one message in each direction through the server's own protocol, and report the messages and the server log. Update the pin to the version you tested. Open a pull request with the before and after server logs, the resolved version, and the list of changed lines.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes the handler signature, the one request_headers line, and the pin in requirements.txt. The description shows the two server logs: the AttributeError and then the TypeError with connection handler failed before the change, and after it a connection that receives the game state, a player-enter message that is broadcast back, and player entered in the log with no traceback.
What a reviewer checks is that the protocol did not change. The JSON message types and fields are the ones the Unity client sends and expects, the broadcast call is untouched, and the only edits are the three lines the new implementation requires. The description lists every handler found so the reviewer can see there was one.
The pull request does not pin websockets back to 13.x to keep the legacy server. That would hold the pin on an implementation the library has replaced, to avoid two edits.
Run it on every dependency bump pull request
A pinned websockets breaks on the pull request that moves the pin, so that is the moment to look. Give the Project an automation with a github trigger on pull_request.opened and a prompt that tells the agent to install the branch's pins, start the server, connect to it and exchange one message through its own protocol, and report any traceback in the server log. The trigger adds the pull request to the prompt; a bump from 10.0 to 14 or later then arrives with the broken handler named before anyone merges it. A pull request a bot opens fires no github trigger, so a Dependabot bump is checked by a schedule trigger with a weekly cron whose prompt tells the agent to check the open dependency pull requests.
For several small websocket services that share this shape, start the request above once per repository from a script with an API key, and read each session's pr_url when its run.completed webhook arrives. Runs past the key's max_concurrent limit are accepted and wait as queued, so the script needs no retry loop.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
Two edits are easy; proving a websocket server works is not, because nothing fails until a client connects, and a client that connects to a broken server gets a close code, not a traceback. An agent in a sandbox starts the real server, writes the client, drives the server's own message protocol, and keeps both the server log and the client's output in the session, so the pull request shows a message going each way rather than a green import.
It also finds the second break. A server with a custom logger fails before the handler is ever called, and only a run against the new release, one failure at a time, shows that there are two lines to change and in which order. A review of the diff alone would see one.
Frequently asked questions
Which websockets release changed the handler signature?
14.0. Up to 13.1, websockets.serve was the legacy server and a two-argument handler worked; the agent verifies that by running one on 13.1. From 14.0 the name points at the new asyncio implementation, which calls the handler with the connection only.
Where did the path argument go?
On the connection: websocket.request.path, next to websocket.request.headers. A handler that routed on the path reads it there; one that ignored it, like the fixture's, drops the parameter.
Can I keep the old implementation by importing from websockets.legacy?
The legacy modules still exist on 17.4, but they are the implementation the library has replaced, so importing them postpones the same two edits. The request above tells the agent to move to the new form and not to pin below 14.
Why did my server log an AttributeError about request_headers before the TypeError?
Because that attribute is read while the server logs the handshake, before the handler runs. The fixture's logger adapter does exactly that, so it fails first and the handler's TypeError appears only after the adapter is fixed. The agent takes them in that order.
Does websockets.broadcast still work?
Yes. It exists on both implementations and the agent leaves the fixture's broadcast calls as they are; the client receives the broadcast player-enter message in the run described above.
More jobs like this: Fix a bug from an alert
- Fix "TypeError: Client.__init__() got an unexpected keyword argument 'proxies'" in httpx (HTTPX)
- Fix "husky - install command is DEPRECATED" and the husky.sh deprecation in husky 9 (husky)
- Fix "AttributeError: 'ImageDraw' object has no attribute 'textsize'" in Pillow 10 (Pillow)
- Fix imageio GIFs That Play With No Frame Delay After Upgrading (mimsave duration) (imageio)
- Fix "SyntaxError: Unexpected identifier 'assert'" in rollup.config.js on Node.js 22 (Rollup)
- Fix "error TS5102: Option 'importsNotUsedAsValues' has been removed" in tsconfig.json (TypeScript)