A student can't get in

Check that you gave out a /s/… link, not the server's home page or an admin key. If the address contains localhost or 127.0.0.1 (on k3s this happens after make host stops), fix the public address: on a k3s server, with sudo scripts/cluster.sh public-url https://… (see correct links); in a local class, give out the link from colloq host. Check HTTPS and access from another network, then the relay or tunnel status. If the teacher can open it from their own network, that doesn't prove the classroom can.

A button is unavailable

Read the message in the interface. Check whether the class has ended, the room rules and the lock on that cell. “Run code” also restricts files and the terminal. The teacher can resume the class or change the rule; reinstalling the server won't help here.

The notebook opens but Python doesn't run

sudo scripts/cluster.sh status
sudo scripts/cluster.sh logs
sudo k3s kubectl -n colloq get pods
sudo k3s kubectl -n colloq get events --sort-by=.lastTimestamp

Check that the broker is running, the pinned image digest is available, there is enough CPU, memory or GPU, and the workspace mount is correct. ImagePullBackOff usually means checking the registry and credentials; Pending means looking for scheduling reasons in the events. A room's memory is reserved in full, so Insufficient memory in the events means the node lacks memory already promised to rooms: lower the memory of this room or of neighbouring rooms in “Resources” (see room resources). The broker waits 20 seconds for such a Pod, then deletes it and reports the cause in the room: the teacher sees how much memory, how many cores or which GPU couldn't be found, students see a short note without the details. In the app log this is a did not start … [unschedulable: memory] line (or cpu, gpu, other). The broker's health check tests API access, not the whole execution path.

Don't swap an unavailable revision for another one without a deliberate decision, and don't connect rooms to a shared Jupyter. Once the cause is fixed, run sudo scripts/cluster.sh smoke and a real cell through the app.

On a server running the ready-made image, start with colloq-host status and colloq-host logs; see Monitoring, logs and reboots.

In a local class (pip install colloq), start with colloq doctor: it checks programs, Docker, the port, the kernel image, files and disk space. colloq logs shows the class log, and docker ps --filter name=colloq-room- lists room containers. If the room says it cannot block access to local addresses, Docker refused the short privileged container that installs this block; the message names the cause, and a class on your own computer explains the block and the COLLOQ_ROOM_NETWORK=open way out.

NameError or changed data

A setup cell may not have been run, the kernel may have restarted, or another participant may have changed shared values. Check the run order. In a Council, each attempt works on personal copies of the data; what carries over between attempts in the notebook’s kernel is files, module settings and anything that could not be copied — an attempt is told about the last of these in its own output. On a pool of workers on machines, an attempt computes on a snapshot of the notebook: it does not see cells run after the snapshot, and its card says which cells the snapshot lacks (“state as of 14:05, without cells 8–9”).

A package won't install or data won't download

In production, kernel traffic out is limited to DNS by default, and the root filesystem is read-only. Prepare the library in an environment image, and upload the data to the room or use an outbound profile the operator has approved. Don't disable network protection for the whole namespace for the sake of one import.

In a local class the internet is open to rooms, but local addresses aren't: a package mirror, a database or a data server on your own network is out of reach, and the connection is refused at once. Put the data into the room, or, if the class is trusted, add COLLOQ_ROOM_NETWORK=open to .env and restart (see a class on your own computer).

CUDA is unavailable

Check the guest VM's driver, the NVIDIA RuntimeClass, allocatable devices, whether a device is free and the catalog's GPU metadata. A CPU environment doesn't become a GPU environment on its own. The shipped GPU environments carry torch 2.14.1 built for CUDA 13.0, which needs driver 580 or newer: nvidia-smi names the driver's version and its CUDA in its header, and on an older driver PyTorch imports but torch.cuda.is_available() is false.

nvidia-smi
sudo k3s kubectl get runtimeclass
sudo k3s kubectl describe node
sudo scripts/cluster.sh gpu-preflight

If a room is using the GPU, the preflight doesn't evict it. Repeat the check at an agreed time when the card is free. A real CUDA run is necessary even when nvidia-smi looks right.

The oracle is silent

Check the oracle access chosen when the class was created, the participant's limit, the time between questions and whether the class has ended. A new participant can ask the oracle only two minutes after joining. A room has a shared hourly cap on questions and handles at most 12 oracle requests at once. The refusal message names the reason and when to try again; these limits don't apply to the teacher. An owner checks the provider's base URL, the model, the key and whether the app can reach the API. A provider error doesn't mean the Python kernel is broken. Don't send secrets to a diagnostic chat.

The disk is filling up

Check the partition that holds /var/lib/colloq and the space for backups. The app's upload limits are not a quota for Python. First find what is growing, save the materials you need, and only then clean up. Don't delete an active room's directory or images the catalog refers to by hand.

Start is blocked after a restore

Look for the message about .restore-in-progress. Repeat the same verified restore with the recovery flags described in the backup guide. Removing the marker by hand can start the app on top of partly restored data.

The class page lacks a file or recent edits

A page is a snapshot of the room at the moment it was published. Edits made after that reach the page the next time the class is ended, if “Update the page every time the class is ended” is on, or with “Update the page”. New notebooks and files are not added by themselves: tick them on the Class page screen, where they are marked “new”. If the page did not update after the class ended, look at the “Check” section: a new key, name or room address in a file stops the update. A teacher can put a withdrawn page back; this doesn't change access to the room's /s/… link.

What to include in a problem report

Give the version, the time, the steps to reproduce, and the expected and actual result. sudo python3 scripts/release.py field --release /var/lib/colloq/releases/current.json --field version shows the installed release's version, and colloq --version shows the local package's version. Add the component status and the events related to the failure. Remove admin links, keys, personal data and cell output you don't need. On Vast, use NAME=hse SINCE=30m scripts/vast.sh logs; logs of deleted Pods may already be gone.

Subsystem status

/api/health reports competition and package-preparation availability separately in capabilities. An unavailable optional executor does not mean that a working classroom is unhealthy.

Staff can use GET /api/instance/operations for queue age, active attempts and retries, cleanup failures, memory/disk reservations, artifact sizes, document save age/failures and Docker recovery. These are counters and states, without notebook contents or credentials. Process failure counters reset after restart; storage and queue totals reflect current durable state.

Temporary Docker outages are retried automatically. Removing a teacher or rotating their sign-in link also revokes existing connections. Disabling AI agent mode stops further actions in accepted turns; previously completed edits remain undoable.