Interactive topic maps from large text collections with cuML acceleration
The Hardware platform column shows where an issue is most relevant. "All hardware platforms" applies to every platform listed in this playbook.
| Symptom | Hardware platform | Cause | Fix |
|---|---|---|---|
Permission denied when downloading Hugging Face models | All hardware platforms | Hugging Face cache not writable | Re-run the cache ownership commands in Instructions Step 1 for your user |
Running as root is not recommended. Use --allow-root to bypass. and JupyterLab exits; port 8888 never opens | Windows with WSL2 (or any shell running as root) | The shell is running as root (for example wsl -d Ubuntu-24.04 -u root) | Run the playbook as a non-root user, or start JupyterLab with jupyter lab --allow-root |
| Conda create fails resolving packages | All hardware platforms | Channel or version pin mismatch | Retry with the exact conda create command from Instructions; ensure network access to rapidsai and conda-forge |
| Pip reports dask/distributed or RAPIDS dependency conflicts | All hardware platforms | datamapplot upgrades dask beyond RAPIDS-compatible pins | Re-pin with python -m pip install "dask==2025.9.1" "distributed==2025.9.1"; BERTopic can still run with the reported conflicts |
PackagesNotFoundError for jupyterlab-widgets | All hardware platforms | Package unavailable on the conda channel | Install with python -m pip install jupyterlab-widgets |
NotJSONError when opening the notebook in JupyterLab | All hardware platforms | Git LFS pointer file not pulled | Run git lfs install and git lfs pull from the playbook assets directory |
| JupyterLab or Streamlit UI not reachable in the browser | All hardware platforms | Port blocked, wrong host, or missing SSH forward | Use http://localhost:8888 (Jupyter) or http://localhost:8501 (Streamlit); from another device use http://<HARDWARE_IP>:<port>; if remote, forward with ssh -N -L 8888:localhost:8888 username@remote_host |
| Notebook runs on CPU only / no GPU speedup | All hardware platforms | Wrong kernel or accelerator not loaded | Select the rapids-25.10 kernel; confirm %load_ext cudf.pandas and %load_ext cuml.accel cells ran successfully; verify nvidia-smi |
CUDA out of memory during embeddings or clustering | All hardware platforms | Workload exceeds available GPU memory | Reduce nrows when loading data; close other GPU applications; confirm free memory with nvidia-smi |
| Dataset download is slow or fails | All hardware platforms | Network interruption or remote host unavailable | Retry wget for Electronics.jsonl.gz; confirm outbound network access |
NOTE
On discrete-GPU hardware platforms, GPU memory is separate from system RAM. CUDA out-of-memory usually means the workload exceeds VRAM: reduce the number of rows processed, lower batch size for embeddings, or close other GPU applications. Use nvidia-smi to confirm no other process is holding memory.
For latest known issues, see the documentation linked under Resources for your hardware platform.