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.

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, changes to objects and files carry over between attempts; personal sheets don't give anyone personal Python memory.

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.

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 reading page has no files or recent edits

This is expected: a publication contains the chosen versions of cells and outputs, not the room's files. After changing the live notebook, publish again. If the page has been withdrawn, a teacher can restore it; 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.