Troubleshooting

Common symptoms

Symptom	Likely cause	Fix
VTK not found during CMake configure	Missing VTK development package	Install your distro’s VTK dev package or use a container.
BLAS not found or LAPACK not found	Missing BLAS/LAPACK implementation	Install OpenBLAS/LAPACK development packages and rerun CMake.
Smoke checker reports missing output directory	Solver did not complete or was launched from the wrong path	Run from the repository root and inspect solver output.
python tools/check_smoke_output.py fails with syntax errors	Python is older than the checker requires	Use Python 3.10 or newer.
mpirun works locally but fails on a cluster	Container MPI does not match host MPI or launcher policy	Use the site-recommended MPI/container binding and update the SLURM template.
CUDA container sees no GPU	Missing GPU allocation or missing --nv	Request a GPU allocation and run through Apptainer/Singularity with --nv.
No permission to build SIF	Cluster disallows root container builds	Pull or provide a prebuilt SIF; do not build as root on the login node.

When opening an issue, include the exact command, KiT-RT commit, CMake options, compiler version, container runtime, and the first failing log excerpt.