Troubleshooting - Nexa Sdk

import Feedback from "/snippets/page-feedback.mdx";

Install / pip

<AccordionGroup> <Accordion title="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](/en/run/python/install#install-via-pip). </Accordion> <Accordion title="Windows SmartScreen blocks the CLI installer"> The `.exe` is not yet code-signed. Click **More info → Run anyway** in the SmartScreen dialog. </Accordion> </AccordionGroup>

CLI

<AccordionGroup> <Accordion title="`geniex` not found after install"> The installer doesn't add itself to `PATH`. Run:

```powershell
Set-Alias geniex (where.exe geniex)
```

</Accordion> <Accordion title="`--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](/en/get-started/platforms#llamacpp). </Accordion> </AccordionGroup>

Server

<AccordionGroup> <Accordion title="`geniex serve` returns 'model not found'"> The server doesn't auto-download. Pull the model first:

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

Then restart `geniex serve`.

</Accordion> <Accordion title="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)](/en/run/cli/install). </Accordion> </AccordionGroup>

Linux

<AccordionGroup> <Accordion title="`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 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 bash
   sudo usermod -aG docker $USER
   newgrp docker        # apply the new group in the current shell
   ```

   Then retry the pull.

</Accordion> <Accordion title="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](/en/run/linux/install#install-host-dependencies). </Accordion> <Accordion title="`--compute npu` fails with `SDKError(Invalid input parameters or handle)` / `Device 'HTP0' not found`"> 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
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
```

</Accordion> <Accordion title="`--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. </Accordion> <Accordion title="`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 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](https://github.com/qualcomm/GenieX/issues) or Slack with the output above.

</Accordion> </AccordionGroup>

Android

<AccordionGroup> <Accordion title="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. </Accordion> <Accordion title="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](/en/run/android/api-reference#modelpullinput). </Accordion> <Accordion title="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`. </Accordion> <Accordion title="`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. </Accordion> </AccordionGroup>

Still stuck?

<CardGroup cols={2}> <Card title="GitHub Issues" icon="github" href="https://github.com/qualcomm/GenieX/issues"> File a bug, request a feature, or browse open issues. </Card> <Card title="Slack" icon="slack" href="https://aihub.qualcomm.com/community/slack"> Developer collaboration. </Card> </CardGroup> <Feedback/>