qualcomm Environment Troubleshooting (base)
🧭 Diagnosis framework:
${APP_ROOT}/factory/chat_features/model-builder/troubleshooting/_diagnosis-framework.md; this SKILL covers environment/dependency/build failures.
Responsibility
Fix WoS ARM64 environment: VS ARM64/MSBuild failures, two-Python split (x64 3.10 conversion vs ARM64 3.13 inference), missing deps, protobuf conflicts, PyTorch --index-url rules. All paths from qairt_env.json (generated by Setup.bat) — never hardcode.
Trigger signals
No CMAKE_C_COMPILER/CMAKE_C_COMPILER not foundVCTargetsPath.vcxproj/BaseOutputPath not set/MSB1009/Failed to run MSBuildModuleNotFoundError: No module named 'qai_appbuilder' / 'cv2' / PILImportError: cannot import name 'builder' from 'google.protobuf.internal'- Unclear which Python env → B10
Core knowledge
Two Python environments
| Env | qairt_env.json key |
Python | Role |
|---|---|---|---|
| Conversion | python_x64_venv |
x86_64 3.10 | ONNX export, qairt-converter, qnn-onnx-converter, qnn-model-lib-generator (all hosts). |
| Runtime | python_runtime_venv (legacy alias python_arm64_venv) |
3.13 — aarch64 on WoS (.venv_arm64_313), x86_64 on x64 Windows (.venv_x64_313) |
qai_appbuilder, QNNContext, inference. |
Default: python_x64_venv (most QAIRT tools link python310.dll → fail under 3.13 with Module use of python310.dll conflicts). Use python_runtime_venv only when importing qai_appbuilder/QNNContext or running inference on .bin/.dlc. Uncertain → B10. Example: GenAIBuilderFactory/libPyNetRun.pyd links python310.dll → must use python_x64_venv.
VS ARM64 / MSBuild issues
qnn-model-lib-generator and qnn-context-binary-generator.exe require the VS ARM64 build env.
CMAKE_C_COMPILER not found—vcvarsall.bat arm64not called orVCTargetsPath→ BuildTools. Fix:call "%_VCVARSALL%" arm64in same.bat(env doesn't propagate acrosscmd /c).VCTargetsPath/BaseOutputPath not set— BuildTools MSBuild can't compile ARM64. Fix:VCTargetsPath→ Community (vc_targets_pathinqairt_env.json). Verify:where.exe MSBuild.exe→...\Community\....
✅ C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Microsoft\VC\v170\
❌ C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\...
qai_appbuilder import error
Use runtime Python (python_runtime_venv; legacy alias python_arm64_venv):
%PYTHON_RUNTIME% -c "import qai_appbuilder; print('OK')"
Still fails → re-run Setup.bat. Offline: data\bin\uv\uv.exe pip install vendor\whl\qai_appbuilder-*.whl.
Missing deps (cv2, Pillow)
Pre-installed by Setup.bat from vendor\whl\:
| Package | Notes |
|---|---|
numpy |
pre-installed |
opencv-python-headless |
headless only. Never install opencv-python (conflicts) |
Pillow |
via pip install -e .; win_arm64 cp313 |
torch/torchvision |
not pre-installed (see index-url rule) |
Fails → re-run Setup.bat. Do NOT pip install opencv-python.
protobuf conflict
cannot import name 'builder' from 'google.protobuf.internal' → onnx/tensorflow version conflict. Fix: re-run Setup.bat.
PyTorch --index-url rules
| Env | Command |
|---|---|
python_x64_venv |
pip install torch torchvision — no --index-url |
python_runtime_venv (aarch64 3.13, WoS) |
uv pip install torch torchvision --index-url https://download.pytorch.org/whl — MUST (ARM64 wheels off-PyPI) |
python_runtime_venv (x86_64 3.13, x64 Win) |
uv pip install torch torchvision — no --index-url (win_amd64 on PyPI) |
python_runtime_venv (other packages, any arch) |
uv pip install <pkg> — no --index-url |
SSLCertVerificationError on weights → Invoke-WebRequest to fetch .pth, re-run export.
Architecture detection
Do NOT use $env:PROCESSOR_ARCHITECTURE / platform.machine() (emulation-affected).
Use (Get-WmiObject Win32_Processor).Architecture (12=ARM64, 9=x64). Never Get-PnpDeviceProperty/Win32_SystemDriver (300-400s hang).
Verify env
$cfg = Get-Content ${APP_ROOT}\data\config\qairt_env.json | ConvertFrom-Json
& "$($cfg.python_x64_venv)\Scripts\python.exe" -c "import onnx; print('conversion env OK')"
& "$($cfg.python_runtime_venv)\Scripts\python.exe" -c "import qai_appbuilder; print('runtime env OK')"
Blocking Conditions
- B10 — correct venv unclear → STOP, ask. Depends on what tool links against.
- B2 —
pip installneeded → stop, state package + reason, ask. - B1 —
qairt_env.jsonvariable empty → stop, list missing vars.
Escalation
Setup.bat re-run doesn't fix, or venv undetermined → stop (B10/B1/B2). Never guess env or install unpinned versions.
Full details → references/win_qairt_setup.md.