Commonly Encountered Problems#
Unable to import Python bindings#
Symptom#
import cuest.bindings
Yields#
Traceback (most recent call last):File “<python-input-0>”, line 1, in <module>import cuest.bindingsModuleNotFoundError: No module named ‘import cuest.bindings’
Troubleshooting#
Make sure that the wheel file has been imported into the currently active
Python (virtual) environment.
Also ensure that appropriate CUDA runtime libraries are in LD_LIBRARY_PATH.
Import Errors#
Symptom#
import cuest.bindings
Yields#
ImportError: /usr/lib/x86_64-linux-gnu/libstdc++.so.6: version GLIBCXX_3.4.31 not found
Troubleshooting#
The binary distribution was compiled with a more recent version of the C/C++ libraries than are present on the machine you’re running on. This can be fixed by running in a virtual environment like Conda with a newer compiler toolchain installed, or using a container. If you reach out to the cuEST development team, they can also provide a distribution compatible with a wider range of C environments.
Runtime Errors#
Symptom#
import cuest.bindings
Yields#
RuntimeError: (‘Unable to allocate CUDA array:’, <cudaError_t.cudaErrorInsufficientDriver: 35>)
Troubleshooting#
In general the CUDA driver on your system needs to be new enough for the CUDA
toolkit used. When installing CUDA Python bindings, pip could select a newer
version that demands a more modern device driver to be used. To fix this, you
can specify the version of the bindings to install, e.g. pip install
cuda-bindings==12.8, where the version should be chosen to correspond to a
CUDA toolkit that can work with your installed device driver. Alternatively,
updating the CUDA device driver will solve the problem.
cuEST Fails to Load (NVRTC / nvJitLink Not Found)#
Symptom#
import cuest.bindings
Yields#
ImportError: libnvrtc.so.13: cannot open shared object file: No such file or directory
Troubleshooting#
cuEST links directly against the CUDA Toolkit’s NVRTC and nvJitLink
runtime-compilation libraries (libnvrtc and libnvJitLink), used for
JIT compilation. If either is missing, loading cuEST
itself fails – on every supported CUDA Toolkit version, not just where JIT
runs. Install the matching CUDA Toolkit components and ensure they are on
LD_LIBRARY_PATH.
JIT-Compiled Routine Falls Back to a Precompiled Kernel on CUDA 12#
Symptom#
A routine documented as JIT-compiled (see the C API reference) appears to skip JIT specialization, or explicitly requesting JIT mode returns:
Yields#
CUEST_STATUS_INVALID_ARGUMENT
Troubleshooting#
JIT compilation requires CUDA Toolkit 13.x or newer (13.0.2 or later). On CUDA
12.x, JIT initialization is skipped at handle creation, so affected routines
run their precompiled kernels instead, and explicitly requesting JIT mode
returns CUEST_STATUS_INVALID_ARGUMENT. Use CUDA Toolkit 13.0.2 or newer to
enable JIT specialization; see Just-In-Time (JIT) Compilation in cuEST.
cuestCreate Returns CUEST_STATUS_INVALID_ARGUMENT for a JIT Setting#
Symptom#
cuestCreate(handle_parameters, &handle)
Yields#
CUEST_STATUS_INVALID_ARGUMENT
Troubleshooting#
A JIT handle parameter was rejected: the configured
CUEST_HANDLE_PARAMETERS_JIT_CACHE_DIR is a symlink or is world-writable
without the sticky bit, or CUEST_HANDLE_PARAMETERS_JIT_COMPILE_THREADS is
below 1. Point the cache directory at a trusted, per-user, non-world-writable
path and use a thread count >= 1; see Controlling JIT Compilation.
JIT Cache Directory Not Writable#
Symptom#
The first compute call into a JIT-compiled routine fails.
Yields#
CUEST_STATUS_EXCEPTION (or an equivalent compute-call failure)
Troubleshooting#
If the configured (or default) JIT cache directory cannot be written, the
compile step fails at the first affected compute call. Choose a writable
location via CUEST_HANDLE_PARAMETERS_JIT_CACHE_DIR, or fix the directory
permissions.
HOME Not Set#
Symptom#
cuestCreate fails on a machine with no explicit JIT cache directory
configured.
Yields#
CUEST_STATUS_HOME_NOT_FOUND
Troubleshooting#
The default JIT cache location is derived from the HOME environment
variable, so handle creation fails if HOME is unset or empty (as can
happen in minimal containers or batch environments) and no cache directory was
configured. Either set HOME or pass an explicit
CUEST_HANDLE_PARAMETERS_JIT_CACHE_DIR.
Unsupported Compute Capability / Architecture for JIT#
Symptom#
The first compute call into a JIT-compiled routine fails on an unusual or very new/old GPU.
Yields#
CUEST_STATUS_EXCEPTION (or an equivalent compute-call failure)
Troubleshooting#
JIT kernels are compiled for the real GPU architecture; a device whose architecture the installed CUDA Toolkit cannot target fails to compile. Use a CUDA Toolkit new enough for the device; see the CUDA version requirements at the top of the JIT compilation page.