Troubleshooting

Common errors and how to fix them.

Install / pip

SSL or certificate errors during pip install (corporate proxy / QDC)

Common on networks with TLS inspection — including Qualcomm Developer Cloud (QDC). Pre-download the SDK and point pip at the local file. See the full PowerShell snippet in Python install.

Windows SmartScreen blocks the CLI installer

The .exe is not yet code-signed. Click More info → Run anyway in the SmartScreen dialog.

CLI

`geniex` not found after install

The installer doesn’t add itself to PATH. Run:

Set-Alias geniex (where.exe geniex)

`--compute cpu` or `--compute gpu` errors with a Qualcomm AI Hub Model

Qualcomm AI Engine Direct is NPU-only. Use --compute npu (or omit the flag — npu is the default for qairt). To run on CPU/GPU, switch to a GGUF model on the llama.cpp runtime.

`Context length exceeded` during a long chat

The conversation outgrew the context window (--nctx, default 4096).

• llama.cpp (GGUF): raise it at runtime, e.g. geniex infer <model> --nctx 8192, up to the model’s trained maximum. A larger window uses more memory.
• Qualcomm AI Engine Direct (NPU): the window is fixed in the compiled bundle and --nctx has no effect. Add --sliding-window to keep chatting (evicts the oldest context), or pull a bundle built for a longer context.

See Increasing the context length.

Server

`geniex serve` returns 'model not found'

The server doesn’t auto-download. Pull the model first:

geniex pull ai-hub-models/Qwen3-4B-Instruct-2507

Then restart geniex serve.

Docker container can't see the NPU

The --privileged flag is required for NPU access. Make sure your docker run includes it, plus the volume mounts for /usr/lib. See CLI install (Docker).

Linux

`docker pull` fails with permission / unauthorized

Two separate things have to be right:

1. Registry login. Docker Hub (docker.io/qualcomm/geniex) is public and needs no login. For the Qualcomm Container Registry, log in first:

   bash

   # Qualcomm Container Registry:
   docker login docker-registry.qualcomm.com -u '$app' -p GB2S6KXMJXTPV8VHNFNS7Q6LVH75LOOBTLT8D723WUX6PSFZMTX95GIQG4EFWH5C021ONZ5763VI9IDHU96Q7VAZJ2830CLX3NPI6STQOJWRYXLLA2ZYTL1S
   

   You should see Login Succeeded.

2. Docker group membership. If docker pull returns permission denied while trying to connect to the docker API at unix:///var/run/docker.sock, your user isn’t in the docker group:

   bash

   sudo usermod -aG docker $USER
   newgrp docker        # apply the new group in the current shell
   

   Then retry the pull.

Container loads model but inference fails with `Failed to create device: 14001`

The container can’t reach the NPU. Make sure your docker run includes --privileged and the /usr/lib mount, and that the host’s Qualcomm driver packages (qcom-adreno1, qcom-fastrpc1) are installed — see Linux install → Install host dependencies.

`--compute npu` fails with `SDKError(Invalid input parameters or handle)` / `Device 'HTP0' not found`

The llama.cpp Hexagon backend dlopens the unversioned libcdsprpc.so, but qcom-fastrpc1 only ships libcdsprpc.so.1. On bare metal install.sh creates the symlink; if you deployed the release tarball directly (no install.sh), create it yourself:

bash

sudo ln -sf /usr/lib/aarch64-linux-gnu/libcdsprpc.so.1 /usr/lib/aarch64-linux-gnu/libcdsprpc.so
sudo ln -sf /usr/lib/aarch64-linux-gnu/libadsprpc.so.1 /usr/lib/aarch64-linux-gnu/libadsprpc.so
sudo ldconfig

`--compute hybrid` runs but at CPU speed (silent NPU fallback)

If the Hexagon driver can’t load (see the entry above), hybrid still produces correct output — it just runs entirely on CPU, so the failure is silent. Confirm the NPU is actually engaged by running with GGML_HEX_VERBOSE=1; you should see Hexagon Arch version vNN and a libggml-htp-vNN.so session. No such lines means it fell back to CPU.

`geniex` exits with 'device is missing CPU features geniex requires'

The aarch64 Linux build is compiled for armv8.2-a with the fp16, dotprod, lse (atomics), and rdm extensions. Baseline armv8.0 boards — some Dragonwing IoT SoCs with no NPU — don’t implement these, so geniex stops at startup with a clear error rather than crashing with a raw SIGILL: illegal instruction partway through a run.

This check is global: every backend needs those instructions, so switching --compute to cpu, gpu, or npu won’t help on such a device. Check what your CPU reports:

bash

LD_SHOW_AUXV=1 /bin/true | grep AT_HWCAP   # look for atomics, asimdrdm, asimddp, fphp, asimdhp
cat /proc/cpuinfo | grep Features          # same features, under the kernel's names

If those features are absent, the device can’t run the current build. Report it in GitHub Issues or Slack with the output above.

Android

Model loads but generation self-repeats or outputs nothing

The demo (or your code) is passing the raw user text into generateStreamFlow instead of the chat-templated prompt. Qualcomm AI Engine Direct pipelines treat their input as already-templated — pass applyChatTemplate().formattedText, not the raw user message.

Qualcomm AI Hub pull fails with `INVALID_INPUT`

Android needs an explicit chipset for Qualcomm AI Hub pulls — auto-detect only runs on Windows on Snapdragon. Set ModelPullInput.chipset to "SM8750" (Snapdragon 8 Elite) or "SM8850" (Snapdragon 8 Elite Gen 5). See Android API reference → ModelPullInput.

Qualcomm AI Engine Direct load fails with 'unknown model name'

The model id returned by Qualcomm AI Hub must match an entry in the Qualcomm AI Engine Direct runtime’s registry (qwen3_4b_instruct_2507, qwen2_5_vl_7b_instruct, etc.). To add a new Qualcomm AI Hub Model, register it on the C++ side first — see third-party/geniex-qairt/models/{llm,vlm}_model_registry.h.

`nGpuLayers` or `nCtx` rejected on Qualcomm AI Engine Direct

Qualcomm AI Hub Models are compiled with fixed KV cache and context length. Leave both nGpuLayers and nCtx at their defaults; tune max_tokens and enable_thinking instead.

Still stuck?

GitHub Issues

File a bug, request a feature, or browse open issues.

Slack

Developer collaboration.

Was this page helpful?

Yes

No