JupyterHub RTC (Real-Time Collaboration) TypeError with DockerSpawner

JupyterHub
,
1

Problem Description

I’m experiencing a critical error when trying to enable Real-Time Collaboration (RTC) in JupyterHub with DockerSpawner. When users open notebooks, the collaboration WebSocket connections fail with a TypeError related to bitwise operations in the pycrdt library.

Error Details

Main Error:


TypeError: unsupported operand type(s) for &: ‘str’ and ‘int’

Full Stack Trace:


[E 2025-11-04 10:41:14.593 ServerApp] Exception in callback functools.partial(<function WebSocketProtocol._run_callback.. at 0xffff81ad39c0>, <Task finished name=‘Task-195’ coro=<YDocWebSocketHandler.on_message() done, defined at /opt/conda/lib/python3.12/site-packages/jupyter_server_ydoc/handlers.py:293> exception=TypeError(“unsupported operand type(s) for &: ‘str’ and ‘int’”)>)

Traceback (most recent call last):

File “/opt/conda/lib/python3.12/site-packages/tornado/ioloop.py”, line 758, in _run_callback

ret = callback()

^^^^^^^^^^

File “/opt/conda/lib/python3.12/site-packages/tornado/websocket.py”, line 668, in

self.stream.io_loop.add_future(result, lambda f: f.result())

^^^^^^^^^^

File “/opt/conda/lib/python3.12/site-packages/jupyter_server_ydoc/handlers.py”, line 298, in on_message

header = decoder.read_var_uint()

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

File “/opt/conda/lib/python3.12/site-packages/pycrdt/_sync.py”, line 190, in read_var_uint

uint += (byte & 127) << i

~~~~~^~~~~

TypeError: unsupported operand type(s) for &: ‘str’ and ‘int’

The error occurs in:

  • /opt/conda/lib/python3.12/site-packages/pycrdt/_sync.py, line 190

  • During WebSocket message processing for collaboration rooms

  • Both global awareness and notebook-specific collaboration rooms

Environment Setup

JupyterHub Configuration

  • JupyterHub Version: 5.3.0

  • Spawner: DockerSpawner 14.0.0

  • Authentication: DummyAuthenticator (for testing)

  • Network: Custom Docker network (galen-network)

Docker Images

JupyterHub Container (galen-jupyterhub):


FROM python:3.11-slim

# Install JupyterHub and dependencies

RUN pip install --no-cache-dir \

“jupyterhub==5.3.0” \

“oauthenticator[azuread]==17.3.0” \

“python-dotenv==1.2.1” \

“dockerspawner==14.0.0” \

“jupyterhub-idle-culler==1.4.0” \

“pycurl==7.45.7” \

“configurable-http-proxy==0.4.0”

JupyterStack Container (galen-jupyterstack):


FROM quay.io/jupyter/scipy-notebook@sha256:766db6b20052ba1b83f89759ff0a2a9a6c3444695af03c2e0f6ef7a96b077e00

USER root

RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# Install collaboration package

RUN pip install --no-cache-dir \

“jupyter-collaboration==4.1.1”

Key Dependencies in JupyterStack Container

  • Python: 3.12.11

  • jupyter-collaboration: 4.1.1

  • jupyter-collaboration-ui: 2.1.1

  • jupyter-docprovider: 2.1.1

  • jupyter-server: 2.16.0

  • jupyter-server-ydoc: 2.1.1

  • jupyter-ydoc: 3.1.0

  • pycrdt: 0.12.43

  • pycrdt-websocket: 0.16.0

  • tornado: 6.5.1

JupyterHub Configuration Highlights


# DockerSpawner Configuration

c.JupyterHub.spawner_class = DockerSpawner

c.DockerSpawner.image = ‘galen-jupyterstack:latest’

c.DockerSpawner.network_name = ‘galen-network’

c.DockerSpawner.use_internal_ip = True

# Default URL for users after login

c.Spawner.default_url = ‘/lab’

# Pre-spawn hook for collaboration setup

def pre_spawn_hook(spawner):

username = spawner.user.name

user_groups = {group.name for group in spawner.user.groups}

if “collaborative” in user_groups:

# Collaboration container setup

spawner.args.append(“–LabApp.collaborative=True”)

spawner.args.append(“–collaborative”)

spawner.args.append(“–allow-root”)

# Volume mounting logic…

c.Spawner.pre_spawn_hook = pre_spawn_hook

Attempted Solutions

  1. Verified Docker network connectivity - containers can communicate

  2. Checked volume mounts - working correctly

  3. Confirmed JupyterLab starts - lab interface loads successfully

  4. Tested without collaboration - works fine when RTC is disabled

Questions

  1. Is this a known compatibility issue between the current versions of pycrdt (0.12.43) and jupyter-server-ydoc (2.1.1)?

  2. Are there specific version combinations that are known to work together for RTC in DockerSpawner environments?

  3. Could this be related to the Python version mismatch between JupyterHub container (Python 3.11) and JupyterStack container (Python 3.12)?

  4. Are there additional configuration steps needed for RTC in DockerSpawner beyond installing jupyter-collaboration?

Additional Context

  • The error suggests that pycrdt is receiving string data where it expects bytes/integers

  • This happens during WebSocket message decoding in the collaboration system

  • The issue occurs immediately when notebooks are opened, preventing any collaboration functionality

  • Regular JupyterLab functionality (without collaboration) works perfectly

Request for Help

Has anyone successfully set up RTC with JupyterHub + DockerSpawner? I’d appreciate:

  • Working version combinations

  • Additional configuration requirements

  • Known workarounds for this specific error

  • Alternative approaches to enable collaboration in containerized environments

Thank you for any insights or suggestions!

-–

System Information:

  • Host OS: macOS

  • JupyterHub deployment: Docker containers with custom network

  • User authentication: Currently using DummyAuthenticator for testing