Potential Bug: receive_bytes raises 1006 instead of 1011

[Harxyz]

#2383 following up on this discussion I don't think this has been solved yet, hence raising it again. Any plans to fix the status code here? On ping timeout a 1006 is being raised instead of 1011 when calling receive_bytes. I have added some code below to reproduce it. Would appreciate if this could be fixed? thanks

server.py

from starlette.applications import Starlette
from starlette.routing import WebSocketRoute
from starlette.websockets import WebSocket, WebSocketDisconnect
import asyncio
from datetime import datetime

async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    print(f"[{datetime.now()}] Client connected")
    
    try:
        await websocket.send_json({"counter": 1})
        await asyncio.sleep(1)
        print("Receiving now")
        data = await websocket.receive_bytes()
        print(f"[{datetime.now()}] Received: {data}")
        
    except WebSocketDisconnect as e:
        print(f"[{datetime.now()}] Disconnected - Code: {e.code}, Reason: {e.reason}")

app = Starlette(routes=[WebSocketRoute("/ws", websocket_endpoint)])

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        app, 
        host="0.0.0.0", 
        port=8000,
        ws_ping_interval=5,
        ws_ping_timeout=10
    )

client.py

import asyncio
import websockets
import time
from datetime import datetime

async def main():
    uri = "ws://localhost:8000/ws"
    print(f"[{datetime.now()}] Connecting to {uri}")
    
    async with websockets.connect(uri) as ws:
        print(f"[{datetime.now()}] Connected")
        msg = await ws.recv()
        print(f"[{datetime.now()}] Received: {msg}")
        print(f"[{datetime.now()}] Blocking for 30s - can't send pongs!")
        time.sleep(30)
        print(f"[{datetime.now()}] Unblocked")

if __name__ == "__main__":
    asyncio.run(main())

Trace

 data = await websocket.receive_bytes()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/python3.11/site-packages/starlette/websockets.py", line 122, in receive_bytes
    self._raise_on_disconnect(message)
  File "/python3.11/site-packages/starlette/websockets.py", line 105, in _raise_on_disconnect
    raise WebSocketDisconnect(message["code"])
starlette.websockets.WebSocketDisconnect: 1006

[nggit]

I think it's not a bug and commonly misunderstood. Close code 1006 is reserved, it's meant to be used internally in server/application. Not send to wire.

In client.py you must do ws.recv() again after sleep to know the real close code sent by Uvicorn, and see it in the client side instead - Which is 1011.

Here is my client's result:

Received (data): b'\x81\r{"counter":1}'
Received (ping): b'\x89\x04B@\xb9-'
Received (close): b'\x88\x18\x03\xf3keepalive ping timeout'
code: 1011

# myclient.py
import time

from netizen import HTTPClient


with HTTPClient('localhost', 8000) as client:
    response = client.send(
        b'GET /ws HTTP/1.1',
        b'Upgrade: websocket',
        b'Connection: Upgrade',
        b'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==',
        b'Sec-WebSocket-Version: 13'
    )

    if response.status == 101:
        print('Received (data):', client.recv(4096))  # b'\x81\r{"counter":1}'
        print('Received (ping):', client.recv(4096))  # server send ping, consume it

        # time.sleep(15)

        close_frame = client.recv(4096)  # real close code
        print('Received (close):', close_frame)

        print('code:', int.from_bytes(close_frame[2:4], 'big'))

[nggit]

however, there is no indication of this on the server side. Instead, the server exits with a status code: 1006 which is extremely obscure and inaccurate.

That's right. Let's talk about the original code first. receive_bytes() code is supposed to have the status code sent by client. But you see 1006.

It's defined in ASGI spec when no known code, then the server should send the default disconnect code (1005) to the app https://asgi.readthedocs.io/en/latest/specs/www.html#disconnect-receive-event-ws

1006 is likely sent by Uvicorn to app, on behalf of the client because Uvicorn want to close the connection before the client close. So no known code from client. And as I said, this code is internal use (between Uvicorn and Starlette).

Because when I run the original code on my ASGI server, the result is different. It shows 1005 not 1006.

[2025-11-23 18:52:17.992454] Client connected
Receiving now
[2025-11-23 18:52:48,996] http_protocol: INFO: receive: WebSocketServerClosed: TimeoutError: receive timeout
[2025-11-23 18:52:48.997076] Disconnected - Code: 1005, Reason: 
[2025-11-23 18:52:48,997] asgi_server: INFO: handler exited early (no close?)

[Harxyz]

Thanks for your response, it does make sense, however, why would there be a difference amongst the original code with receive_bytes and the new code with the send_json after the sleep. The second send_json shows the sent 1011 whereas the receive_bytes does not. As per the asgi spec shouldn't both have identical status codes if they are not receiving a pong back from the client i.e 1005 a default disconnect.

[nggit]

For your second code with send_json(), it seems because timing-related issue, you add 20 seconds and client got 1011 as expected.

But I still see 1006 on server.

[Harxyz]

The sleep on the server is meant to reflect sending a message after the ping timeout of the client. After which we I see a 1011 not 1006 on the server side (for the second scenarios send_json after sleep) which leads me to ask why this isn't also the case for receive_bytes why are there different status codes for receive_bytes and send_json on the server side.

[nggit]

Previously I added ws.recv() in your client.py after sleep and forgot to remove it. That's why I see 1011 on client.

I tried again with your second code and original client, I still see 1006 in server. And now I don't see 1011 at all in the client.

But:

The sleep on the server is meant to reflect sending a message after the ping timeout of the client

does't work as intended.

This one does "send after the ping timeout".

async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    print(f"[{datetime.now()}] Client connected")
    
    try:
        await websocket.send_json({"counter": 1})

        print("Receiving now")
        data = await websocket.receive_bytes()
        print(f"[{datetime.now()}] Received: {data}")
    except WebSocketDisconnect as e:
        print(f"[{datetime.now()}] Disconnected - Code: {e.code}, Reason: {e.reason}")

    # send after disconnect
    await websocket.send_json({"counter": 2})