Troubleshooting

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:

Registry. Pull from Docker Hub (docker.io/qualcomm/geniex), which is public and needs no login. If you see unauthorized, check the image name and tag against CLI install (Docker).
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.

VLM with --compute npu aborts with HTP0 buffer mapping failed (SIGABRT)

By default the vision encoder (mmproj) shares the single HTP session with the language model, and on some devices (e.g. QCS9075) the two don’t fit together. Give the vision encoder its own HTP session:

bash

GGML_HEXAGON_DEVICES=2 geniex infer unsloth/Qwen3-VL-2B-Instruct-GGUF:Q4_0 --compute HTP0 --vit-compute HTP1

Use --vit-compute CPU instead if you’d rather keep the vision encoder off the NPU. GGML_HEXAGON_DEVICES=2 is the non-deprecated spelling of the variable; it must be set in the shell that launches geniex (or geniex serve).

--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, install the CPU-only build instead. It is compiled for plain armv8.0-a with no ISA extensions, ships CPU inference only (no QAIRT/NPU, no OpenCL/GPU, no Hexagon), and is correspondingly slower — ggml falls back to its fp32 quant kernels without dotprod/fp16. Every channel asks for it explicitly; nothing is auto-detected:

bash

curl -fsSL https://raw.githubusercontent.com/qualcomm/GenieX/main/cli/release/linux/install.sh | sh -s -- --cpu-only

Channel	How to select the CPU-only build
`install.sh`	`--cpu-only`
`pip install geniex`	`GENIEX_SDK_VARIANT=cpu`
Docker	the `-cpu` tag — `docker.io/qualcomm/geniex:latest-cpu`

geniex-qairt has no CPU-only build at all: QAIRT needs an NPU, and these boards have none. Use geniex-llama-cpp (or the geniex meta package, which drops the QAIRT backend automatically on such a board).If the CPU-only build still fails, report it in GitHub Issues or Slack with the output above.

Gemma 4 E2B is OOM-killed on RB3 Gen 2 (QCS6490)

As a VLM the model needs ~4.94 GB — 3.04 GB of Q4_0 weights plus a 1.9 GB F32 mmproj projector — against the ~4.7 GB this board has available, so the kernel kills the process while the projector loads:

Out of memory: Killed process 19714 (geniex) total-vm:7849464kB, anon-rss:0kB, file-rss:771016kB

Record the model as an llm to run its text path only — that skips the projector and fits. Image and audio input are unavailable in this mode.

bash

geniex pull google/gemma-4-E2B-it-qat-q4_0-gguf
geniex model set-type google/gemma-4-E2B-it-qat-q4_0-gguf llm
geniex infer google/gemma-4-E2B-it-qat-q4_0-gguf

See geniex model set-type.

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.

Init fails with 'this device's CPU lacks features required by geniex'

The same startup guard as on Linux. The default AAR is compiled for armv8.7-a with the fp16, dotprod, and i8mm extensions, but minSdk 27 still admits phones that predate them, so geniex_init returns NOT_SUPPORTED instead of crashing with a raw SIGILL partway through a run.Ship the CPU-only AAR on those devices — geniex-android-aar-cpu-<tag>.aar from the release assets. It is compiled for plain armv8.0-a with no ISA extensions, ships CPU inference only (no Qualcomm AI Engine Direct, no OpenCL, no Hexagon), and is correspondingly slower. Otherwise it is a drop-in replacement: same com.geniex.sdk namespace and API. Only the default AAR is published to Maven Central.

Still stuck?

GitHub Issues

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

Slack

Developer collaboration.

Was this page helpful?

Yes

Get Started

Run

Tutorials

Resources

Install / pip

CLI

Server

Linux

Android

Still stuck?

GitHub Issues

Slack

​Install / pip

​CLI

​Server

​Linux

​Android

​Still stuck?

GitHub Issues

Slack

Install / pip

CLI

Server

Linux

Android

Still stuck?