> For the complete documentation index, see [llms.txt](https://docs.vex-nx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vex-nx.com/getting-started/troubleshooting.md).

# Troubleshooting

![System checks for troubleshooting](https://1807546539-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhgHCHWL3861o2DBW53aA%2Fuploads%2FDuh5rzclbBuDf9rd95hE%2Fve20261112v5-infrastructure.png?alt=media)

## Goal

Fix the most common appliance and lab failures quickly.

Use this structure for each issue: **Problem** -> **Symptoms** -> **Cause** -> **Diagnosis** -> **Solution** -> **Verification**.

***

## Cannot open web UI

**Symptoms:** Browser timeout or connection refused to the management IP.

**Diagnosis:** Check management IP, Bridged NIC, `sudo systemctl status pram-api nginx`.

**Solution:** [Management network](/getting-started/management-network.md); wait for first-boot; restart `pram-api` if needed.

**Verification:** `curl -fsS http://127.0.0.1:8080/api/v1/health` on the appliance shows `"status":"ok"`.

***

## `/dev/kvm` missing / QEMU Start fails

**Symptoms:** Start fails mentioning KVM / acceleration; guests extremely slow.

**Diagnosis:** `ls -l /dev/kvm`

**Solution:** On VMware host set hypervisor launch type off and reboot Windows when required; enable VT-x/EPT on the VM; prefer bare metal for deep nesting. See System requirements.

**Verification:** `/dev/kvm` exists; light guest reaches running within a reasonable time.

***

## Insufficient RAM / Launch Budget

**Symptoms:** Start fails or host becomes unresponsive; Home Launch Budget red.

**Cause:** Sum of node RAM exceeds usable host memory.

**Solution:** Stop unused labs; reduce node RAM; check **Home -> Launch Budget**; size the VM per Sizing and upgrades.

**Verification:** Launch Budget shows headroom; Start succeeds.

***

## Docker / FRR / Alpine starters fail

**Symptoms:** Docker node Start fails; missing FRR/Alpine images.

**Diagnosis:**

```bash
sudo systemctl status docker
sudo vexnx-seed-docker
docker images | grep -E 'frr|alpine'
```

**Solution:** Re-seed after Docker is up. If pull fails on DNS, set DNS under Infrastructure -> Management network, then seed again. Wipe + Start nodes after images load.

**Verification:** `docker images` lists FRR and Alpine; node status running.

***

## Convert & add / upload fails

**Symptoms:** Import stuck or errors on disk space.

**Diagnosis:** Free space on disk 1; browser stayed open; staging path exists.

**Solution:** Expand disk; free `/opt/pram/images`; retry; for Bulk use staging under `/opt/vex-nx/staging/...`.

***

## SCP Permission denied on staging

**Symptoms:** SCP to staging fails.

**Diagnosis:** SSH as **vexnx** (not GUI admin). Staging dirs should be writable.

**Solution:** `sudo systemctl restart pram-api` (ExecStartPre recreates drop zones).

***

## SecureCRT / PuTTY does not open

**Problem:** External console fails or never launches (or UI still forces a per-node `.cmd`).

**Expected:** After one Client Pack install, **Open in SecureCRT/PuTTY** uses `vexnx-console://` and opens the client with no manual `.cmd`. `connect.cmd` is fallback only.

**Symptoms:** Nothing happens; helper MessageBox; `last-launch.log` shows ERROR; wrong device; browser only downloads `.cmd`.

**Cause:** Helper not installed / outdated; protocol registered to `.cmd`; stale `clients.json`; SecureCRT/PuTTY path not found; node stopped; TCP 8022 blocked; browser blocked the protocol after `await` (fixed in current UI via sync `about:blank` handoff).

**Diagnosis:**

* Node status is **running**
* `%LOCALAPPDATA%\VEX-NX\console-helper\last-launch.log` shows `detect stage=` and `Start-Process OK`
* Registry open command uses `powershell.exe` ... `vexnx-console-launch.ps1` (not a `.cmd` handler)
* `Test-NetConnection <appliance-ip> -Port 8022`

**Solution:**

1. Re-download **Windows Client Pack** from the lab UI after appliance updates
2. Unzip and run `install.cmd -Repair` (clears registry + helper folder including stale `clients.json`, then reinstalls)
   * Full wipe of env overrides: `install.cmd -Uninstall -ClearEnv` then `install.cmd`
3. Ensure SecureCRT/PuTTY exists (Program Files, Downloads, or set `VEXNX_SECURECRT` / `VEXNX_PUTTY`; picker runs if not found)
4. Allow outbound TCP **8022**
5. Fallback only: download **connect.cmd** for one node

**Verification:** Log shows `Start-Process OK`; SecureCRT/PuTTY session opens to the correct node username on port 8022 without double-clicking a downloaded `.cmd`.

Details: [Operate and consoles](/labs/operate-and-consoles.md).

***

## Day-0 / ScriptPad config miss

**Symptoms:** After Wipe+Start, hostname from ScriptPad not applied; `configVerify` stays `day0-miss` or `inject-failed`.

**Cause:** Day-0 ISO not consumed; UART busy; guest still in POAP/setup; unsupported plugin path.

**Solution:** Keep ScriptPad saved+active; Wipe then Start; open serial early; close extra SecureCRT sessions during inject; give enough RAM/KVM; retry. See ScriptPad section in [Operate and consoles](/labs/operate-and-consoles.md).

**Verification:** Guest shows expected hostname; `configVerify` is `ok` or `injected`.

***

## Assist timeout

**Symptoms:** Assist dock errors or chips disabled.

**Diagnosis:** OpenRouter key, model, outbound network, host CPU; edition includes Assist.

**Solution:** Assist LLM settings; Test from Admin; see [Using Assist](/assist/using-assist.md).

***

## Junos / heavy guest too slow

**Solution:** More vCPU/RAM; prefer bare-metal ISO; Stop/Start not Wipe after first good boot.

***

## Compatibility still Experimental

**Solution:** Import does not change status. See [Catalog and Compatibility](/images/catalog-and-compatibility.md).

***

## Related

* [FAQ](/getting-started/faq.md)
* [Quick reference](/getting-started/quick-reference.md)
* [Terminology](/getting-started/terminology.md)
* Maintenance


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.vex-nx.com/getting-started/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.