Skip to main content
Version: 0.8.x [Latest Beta]

Troubleshooting

When reporting a problem, always include:

  1. your OS and architecture
  2. your SDK language and version (Python version or C compiler)
  3. example files with which the problem can be reproduced
  4. a minimal reproduction script or project
  5. your hardware details
  6. your execution provider or export target
  7. the full initialization error or stack trace

Enable SDK logs​

import denkflow
denkflow.set_log_level("DEBUG")

Use TRACE only when you need maximum detail.

Enable ONNX runtime logs​

export DENKFLOW_ENABLE_ORT_LOGS=true

Common problems​

Provider not available​

Symptoms:

  • Initialization fails immediately
  • The expected execution provider is missing

Check:

  1. whether the correct denkflow[...] extra was installed
  2. whether the required system stack is installed, for example CUDA, TensorRT, or Intel drivers
  3. whether your Python environment can import onnxruntime
  4. whether ORT_DYLIB_PATH must be set manually
import onnxruntime as ort
print(ort.get_available_providers())

TensorRT is slow on first run​

This is expected. TensorRT builds an optimized engine on the first run of a new model. Persist the SDK data directory (by default $HOME/.config/denkflow on Linux, e.g. mount a host volume at /root/.config/denkflow in Docker) so later runs can reuse the cache.

Offline license stops working after container restart​

Usually one of these is missing:

  • persistent storage for the SDK data directory (default path on Linux as root: /root/.config/denkflow, or a host mount at whatever path DENKFLOW_DATA_DIRECTORY points to)
  • stable /etc/machine-id
  • reused container volume

OpenVINO runs on the wrong device​

Check the device_id mapping. See Runtime and Device Selection > Runtime specific notes.

OpenVINO fails with "Failed to load shared library"​

This error from ONNX Runtime usually means one of two things:

1. Provider shared libraries not found​

ONNX Runtime loads the OpenVINO execution provider via dlopen at runtime. On Linux, the directory containing libonnxruntime_providers_shared.so and libonnxruntime_providers_openvino.so must be discoverable by the dynamic linker.

For packaged releases where all .so files are in the same directory as the binary:

export LD_LIBRARY_PATH="$(dirname ./denkflow-ui):$LD_LIBRARY_PATH"

For development builds with cargo run:

export LD_LIBRARY_PATH="$(pwd)/target/release:$LD_LIBRARY_PATH"
cargo run --release -p denkflow-ui --features camera

On Windows this is not needed because DLLs next to the .exe are found automatically.

2. OpenVINO GPU plugin cannot find the OpenCL runtime​

When using OpenVINO with an Intel GPU (device_id >= 0), the OpenVINO GPU plugin requires:

  • libOpenCL.so.1 — the OpenCL ICD loader
  • Intel compute-runtime — the Intel GPU OpenCL driver, registered via an ICD file

On Ubuntu / Debian:

sudo apt install ocl-icd-libopencl1 intel-opencl-icd

On Fedora / RHEL:

sudo dnf install ocl-icd intel-opencl

On NixOS, these are available but not always on the default library path. Set the environment manually:

# Point to the OpenCL ICD loader
export LD_LIBRARY_PATH="/path/to/ocl-icd/lib:$LD_LIBRARY_PATH"

# Tell the ICD loader where to find the Intel GPU driver
export OCL_ICD_VENDORS=/path/to/intel-compute-runtime/etc/OpenCL/vendors

On Windows, the Intel GPU driver installation includes OpenCL support — no extra steps are needed.

To verify OpenCL device visibility:

# Install clinfo if needed, then:
clinfo -l

If no Intel GPU appears, the compute-runtime driver is missing or OCL_ICD_VENDORS is not set correctly.

DirectML QDQ or Intel export does not behave like FP32​

That is expected. Intel export targets (INTEL_CPU, INTEL_GPU, INTEL_NPU) and DirectML QDQ exports include INT8 quantization by design. The SDK does not convert FP32 to QDQ locally during inference.

Import fails because ONNX runtime library cannot be found​

Set ORT_DYLIB_PATH manually to the ONNX Runtime shared library path. Then retry the import.

Benchmark numbers look worse than expected​

Common reasons:

  • measuring the first TensorRT run instead of steady state
  • not pinning the deployment to the actual target hardware
  • missing GPU driver or runtime dependency, causing CPU fallback
  • not using the export target intended for that hardware