> ## Documentation Index
> Fetch the complete documentation index at: https://geniex.aihub.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to fix them.

## **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 theme={"dark"}
    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 theme={"dark"}
    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 theme={"dark"}
       # 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={"dark"}
       sudo usermod -aG docker $USER
       newgrp docker        # apply the new group in the current shell
       ```

       Then retry the pull.
  </Accordion>

  <Accordion title="`geniex` install.sh reports missing shared libraries">
    On a fresh Ubuntu 24.04 ARM64 host (e.g. IQ9075 EVK), `install.sh` — and, for Docker, the pre-flight `check.sh` / container `entrypoint.sh` — check for libraries like `libCB.so.1`, `libOpenCL_adreno.so.1`, `libcdsprpc.so.1.0.0`, `libgsl.so.1`, `libllvm-*.so.1`, `libpropertyvault.so.0.0.0`, `libdmabufheap.so.0.0.0`, plus Debian's `libatomic1` / `libglib2.0-0`. Install them **on the host** in two steps — if you're inside the geniex container, `exit` first.

    **1. Standard APT packages**

    Addresses the `libatomic1` and `libglib2.0-0` requirements reported by the `geniex` installer, and provides a generic OpenCL ICD loader:

    ```bash bash theme={"dark"}
    sudo apt update
    sudo apt install -y \
      libatomic1 \
      libglib2.0-0 \
      ocl-icd-libopencl1
    ```

    <Note>`ocl-icd-libopencl1` is replaced by `qcom-adreno1` in the next step.</Note>

    **2. Qualcomm driver packages (via `ubuntu-qcom-iot` PPA)**

    Provides the Qualcomm-proprietary libraries required by `geniex`:

    | Missing library                                                                                | Provided by                                          |
    | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
    | `libOpenCL_adreno.so.1`, `libCB.so.1`, `libadreno_utils.so.1`, `libgsl.so.1`, `libllvm-*.so.1` | `qcom-adreno1`                                       |
    | `libdmabufheap.so.0.0.0`                                                                       | `qcom-libdmabufheap` *(auto-dep of `qcom-adreno1`)*  |
    | `libpropertyvault.so.0.0.0`                                                                    | `qcom-property-vault` *(auto-dep of `qcom-adreno1`)* |
    | `libcdsprpc.so.1.0.0`                                                                          | `qcom-fastrpc1`                                      |

    ```bash bash theme={"dark"}
    sudo apt-get install -y qcom-adreno1 qcom-fastrpc1
    ```

    The PPA (`ppa:ubuntu-qcom-iot/qcom-ppa`) is pre-configured on the IQ9075 EVK Ubuntu image. `qcom-adreno1` automatically pulls in `qcom-libdmabufheap` and `qcom-property-vault`.

    After this, re-run `install.sh` (bare metal) or restart the container to confirm; the "Linking host NPU libraries" step should succeed. If `libcdsprpc.so` / `libadsprpc.so` symlinks are still missing on bare metal, re-run `install.sh` to recreate them.
  </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 the missing-libraries entry 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>

<br />

<div class="feedback-wrapper">
  <span class="feedback-label">Was this page helpful?</span>

  <div class="feedback-toggle">
    <input type="radio" name="feedback" id="feedback-yes" class="feedback-input" />

    <label for="feedback-yes" class="feedback-button">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-0801e48b/Images/FeedBack/thumbs-up.svg" alt="Thumbs up" class="feedback-icon" noZoom />

      Yes
    </label>

    <input type="radio" name="feedback" id="feedback-no" class="feedback-input" />

    <label for="feedback-no" class="feedback-button">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-0801e48b/Images/FeedBack/thumbs-down.svg" alt="Thumbs down" class="feedback-icon" noZoom />

      No
    </label>
  </div>
</div>