env-troubleshooting git:20260822.fbacac1C

Immutable. This exact content never changes and is served at /api/v1/blob/acd9e50e5ec1d756.

---
skill_id: env-troubleshooting
tier: base
triggers: ["VCTargetsPath", "No CMAKE_C_COMPILER", "BaseOutputPath", "ModuleNotFoundError cv2", "ModuleNotFoundError Pillow", "qai_appbuilder import error", "B10"]
sources: ["references/win_qairt_setup.md", "SKILL.md Python env section"]
---

# 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 found`
- `VCTargetsPath.vcxproj` / `BaseOutputPath not set` / `MSB1009` / `Failed to run MSBuild`
- `ModuleNotFoundError: No module named 'qai_appbuilder' / 'cv2' / PIL`
- `ImportError: 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 arm64` not called or `VCTargetsPath` → BuildTools. Fix: `call "%_VCVARSALL%" arm64` in same `.bat` (env doesn't propagate across `cmd /c`).
- **`VCTargetsPath` / `BaseOutputPath not set`** — BuildTools MSBuild can't compile ARM64. Fix: `VCTargetsPath` → **Community** (`vc_targets_path` in `qairt_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`):
```bat
%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
```powershell
$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 install` needed → stop, state package + reason, ask.
- **B1** — `qairt_env.json` variable 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`.