> ## Documentation Index
> Fetch the complete documentation index at: https://qualcomm-0801e48b-fix-serve-reasoning-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Common errors and how to fix them.
## **Install / pip**
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](/en/run/python/install#install-via-pip).
The `.exe` is not yet code-signed. Click **More info → Run anyway** in the SmartScreen dialog.
## **CLI**
The installer doesn't add itself to `PATH`. Run:
```powershell theme={null}
Set-Alias geniex (where.exe geniex)
```
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](/en/get-started/platforms#llamacpp).
The conversation outgrew the context window (`--nctx`, default 4096).
* **llama.cpp (GGUF):** raise it at runtime, e.g. `geniex infer --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](/en/run/cli/reference#increasing-the-context-length).
## **Server**
The server doesn't auto-download. Pull the model first:
```bash theme={null}
geniex pull ai-hub-models/Qwen3-4B-Instruct-2507
```
Then restart `geniex serve`.
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)](/en/run/cli/install).
## **Linux**
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 bash theme={null}
# 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 bash theme={null}
sudo usermod -aG docker $USER
newgrp docker # apply the new group in the current shell
```
Then retry the pull.
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](/en/run/linux/install#install-host-dependencies).
The llama.cpp Hexagon backend `dlopen`s 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 bash theme={null}
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
```
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.
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 bash theme={null}
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](https://github.com/qualcomm/GenieX/issues) or Slack with the output above.
## **Android**
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.
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](/en/run/android/api-reference#modelpullinput).
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`.
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?**
File a bug, request a feature, or browse open issues.
Developer collaboration.