Skip to content

Troubleshooting

Start with the symptom that matches what you see. The repair commands are idempotent and do not require deleting a valid installation.

Python cannot import encodings

Typical output:

Fatal Python error: init_fs_encoding
ModuleNotFoundError: No module named 'encodings'

Cause: SWAN's LCG PYTHONHOME or PYTHONPATH was inherited by a different Python executable used by CMS/SCRAM.

Repair:

git pull --ff-only
./install.sh

Current versions of install.sh and activate.sh clear the incompatible prefix variables before invoking CMS/SCRAM.

Kernel installation targets read-only CVMFS

Typical output:

OSError: [Errno 30] Read-only file system: '/cvmfs/.../share/jupyter/kernels/combine-v11'

Cause: jupyter kernelspec install --user inherited SWAN's CVMFS-backed JUPYTER_DATA_DIR.

Repair:

git pull --ff-only
./scripts/install_kernel.sh

The registration script explicitly installs the persistent copy in a writable CERNBox data directory.

jupyter kernelspec list sees the kernel, but the picker does not

This is the most important SWAN-specific distinction. The terminal sees the persistent CERNBox kernelspec, while the running notebook server uses a session-local registry created under /home/$USER.

For the current session:

./scripts/install_kernel.sh

Then refresh JupyterLab and reopen the kernel picker. For later sessions, configure this checkout's swan_env.sh as the SWAN Environment script and start a new session.

The expected picker label is:

Python 3 (CMSSW_16_0_0 + Combine v11.0.0)

The repository was moved

The rendered kernelspec stores an absolute launcher path. Regenerate it after moving or renaming the checkout:

./scripts/install_kernel.sh

Also update the SWAN Environment script setting if its absolute path changed.

The checkout has the wrong Combine tag

The installer refuses to silently reuse a checkout that is not exactly v11.0.0. The safest supported configuration is a fresh repository-local CMSSW area. If this is an intentionally customized installation, move it aside and rerun the installer with the default path; do not overwrite research files without checking them first.

To rebuild a correctly tagged checkout:

./install.sh --rebuild

Imports work in a terminal but not in the notebook

Confirm that the notebook is using combine-v11, not SWAN's generic python3 kernel. In Python:

import os
print(os.environ.get("CMSSW_VERSION"))
print(os.environ.get("COMBINE_SWAN_ROOT"))

Both values should be populated. If they are absent, select the dedicated kernel and restart it.

A normal SWAN or Coffea notebook breaks after setup

Do not source activate.sh from the SWAN Environment script. Configure swan_env.sh instead. Normal Coffea/LCG notebooks should continue using SWAN's default Python kernel; select combine-v11 only for Combine/CMSSW work.

Collect a focused diagnostic

From the repository root:

git status --short --branch
./scripts/test_scaffold.sh
./scripts/check_setup.sh
jupyter kernelspec list

When reporting a problem, include the SWAN platform and LCG stack, the failing command, and the first complete traceback. Do not include access tokens or credentials.