[Bug]: AssertionError in EventSub in _cleanup() / _listen() after WebSocket reconnect

[Catsanova]

What actually happened?

Using EventSub Conduits I've seen this error occur every so often on websocket reconnects, but mostly ignored it because it never seemed to cause a problem however, this time caused a crash/restart on the container.

It looks like it's is trying to clean up the websocket connection after it times out or disconnects, but for some reason _token_for isn’t set like it’s supposed to be.

All my app and user tokens are still valid, and ManagedHTTPClient is loading them fine, so it doesn’t seem like the problem is with the tokens.

2025-10-25 08:28:42,129 WARNING  twitchio.eventsub.websockets Conduit Websocket "AgoQ5DFD*****" needs to close unexpectedly. Bot will attempt to reassociate this shard if possible.

2025-10-25 08:28:42,130 INFO     twitchio.eventsub.websockets Successfully closed Conduit Websocket: "AgoQ5DFDFEoVR****"

2025-10-25 08:28:42,299 INFO     twitchio.eventsub.websockets Received "session_welcome" message from Conduit Websocket: "AgoQboVyzta****"

2025-10-25 08:28:42,436 INFO     twitchio.client Associated shards with ConduitInfo(conduit="*****", shard_count=2) successfully. Shards: 2 / 2 (connected / Conduit total).

2025-10-25 08:28:59,016 INFO     twitchio.eventsub.websockets Successfully closed EventSub Websocket: "AgoQUKQd****"

2025-10-25 08:30:45,742 ERROR    asyncio Task exception was never retrieved

future: <Task finished name='Task-7005' coro=<Websocket.connect() done, defined at /usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py:185> exception=AssertionError()>

Traceback (most recent call last):

  File "/usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py", line 242, in connect

    await self._ready.wait()

  File "/usr/local/lib/python3.11/asyncio/locks.py", line 213, in wait

    await fut

asyncio.exceptions.CancelledError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):

  File "/usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py", line 241, in connect

    async with asyncio.timeout(10 + 1):

  File "/usr/local/lib/python3.11/asyncio/timeouts.py", line 115, in __aexit__

    raise TimeoutError from exc_val

�
TimeoutError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):

  File "/usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py", line 244, in connect

    await self.close()

  File "/usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py", line 511, in close

    self._cleanup()

  File "/usr/local/lib/python3.11/site-packages/twitchio/eventsub/websockets.py", line 498, in _cleanup

    assert self._token_for

           ^^^^^^^^^^^^^^^

AssertionError

I'm using sentry and it's also detecting an error in _listen() which I did not see in the regular console logs. It's a separate error that occurs independently but I think its also related.

Traceback (most recent call last):
  File "twitchio/eventsub/websockets.py", line 398, in _listen
    await self._process_reconnect(reconnect_data)
  File "twitchio/eventsub/websockets.py", line 461, in _process_reconnect
    await self._reconnect(url=data["payload"]["session"]["reconnect_url"])
  File "twitchio/eventsub/websockets.py", line 318, in _reconnect
    await self.close()
  File "twitchio/eventsub/websockets.py", line 511, in close
    self._cleanup()
  File "twitchio/eventsub/websockets.py", line 498, in _cleanup
    assert self._token_for
AssertionError: null

What did you expect to happen instead?

Expected library to handle the reconnect/cleanup without crashing. Basically, the bot should have just reconnected and kept running like it normally does after a temporary timeout.

Usually it does keep chugging along, not sure why this particular instance was different.

Minimum reproducible example:

Steps to reproduce the problem

Not sure how to directly reproduce since it occurs with varying frequency. Doesn't happen on every reconnect or even every day, could be up to 5 or 10 times or none at all on a given day.

All I'm running is Conduits w/ Autobot, tokens stored in SQLite. Running the code 24/7 should have this error occur at some point.

Screenshot below is to show the frequency of the error occurring over 30 days.

Additional logs:

No response

System and Environment information

twitchio version: 3.10
Python version: 3.11
Operating System: Ubuntu 22.04 (docker)
Connection Method: AutoBot

[chillymosh]

Whilst we look into this, could you try running your bot with the -O flag and see if it raises an error after the assert, since -O ignores all assertions. e.g. python -O main.py

I am leaning towards a guard clause here rather than an assert.

if self._token_for is None:
        logger.debug(
            "%s '%s' cleaned up before token assignment (likely early timeout). Skipping deregistration.",
            self._log_name,
            self,
        )
        return

[Catsanova]

Sure will do!

[EvieePy]

Whilst we look into this, could you try running your bot with the -O flag and see if it raises an error after the assert, since -O ignores all assertions. e.g. python -O main.py

I am leaning towards a guard clause here rather than an assert.

if self._token_for is None:
logger.debug(
"%s '%s' cleaned up before token assignment (likely early timeout). Skipping deregistration.",
self._log_name,
self,
)
return

I'm not sure this is the problem. The logs say Successfully closed EventSub Websocket which means that no Shard-ID was ever passed to this websocket indicating it either was never started/created from a Conduit OR somehow the AutoClient/Bot is not assigning the Conduit Websocket with an appropriate shard.

[EvieePy]

The logging name gets set in __init__. So it is happening at initialization of the websocket.

self._log_name = "EventSub Websocket" if self._shard_id is None else "Conduit Websocket"

[EvieePy]

@Catsanova I have pushed a potential fix a35f6a0...e5671ae. Please update from GitHub master and let me know if the issue continues to occur. I will try and monitor this as well.

[EvieePy]

Hey @Catsanova Just checking in to see how this issue has been going on that release?

[Clasko]

I had the same issue from time to time. The fix seems to work for me.

[Catsanova]

@EvieePy seems to be good so far, have not seen any new errors since!