> 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/vex-nx-user-guide-1/reference/troubleshooting.md).

# Troubleshooting

Format: symptom -> what to check -> fix.

## Management IP / console Keep-Change menu

**Check**

* VGA shows Keep / Change / Reset after install (Keep default **20s**)
* `cat /etc/pram/mgmt-net.json`
* `ip -4 addr show ens160`
* UI: **Infrastructure -> Management network** (live vs saved)

**Fix**

* Wrong Static: reboot -> **Change** -> Static with corrected values, or **Reset to DHCP**
* GUI Static not applied: Save in UI, reboot, choose **Keep** (or wait 20s)
* Cannot reach UI: confirm VMnet0 / port group for Management; Internet (ens161) should stay DHCP on VMnet8 for egress

Full guide: Management network.

## Web UI never loads

**Check**

```bash
sudo systemctl status pram-api nginx
curl -s http://127.0.0.1/api/v1/health
sudo tail -80 /var/log/vexnx-install.log
```

**Fix** - wait for first-boot install; repair with `sudo vexnx-repair` if the payload was updated; confirm you are using the management IP, not `172.17.0.1`.

## KVM unavailable / QEMU painfully slow

**Check** - Infrastructure nested virt hint; VM processor settings.

**Fix** - Power off -> enable VT-x/EPT (or AMD-V/RVI) -> power on. Wipe stuck QEMU nodes after KVM becomes available.

## vJunos boots for a long time / stuck after "starting QEMU to bringup VCP"

**Check** - node vCPU/RAM (want about **8 / 8 GB**); nested KVM available; console shows positive `VCPMEM` / `VCPCPU` (not negative memory).

**Fix** - Conversion or rename to `virtioa.qcow2` does **not** speed Junos. Raise node CPUs (spare cores go to the inner VCP). Prefer bare-metal VEX-NX over VMware-on-Windows. Wait for first Junos login (often 10-20+ minutes under deep nesting). After a good boot use **Stop/Start**, not Wipe.

## Docker / FRR starters fail

**Check**

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

**Fix** - Finish install phase 2; re-seed; Wipe + Start the lab nodes.

## Convert & add or upload fails (Bad Gateway / disk)

**Check** - free space on Hard Disk 1; browser stayed open during multi-GB upload; for Bulk, staging path exists under `/opt/vex-nx/staging/...`.

**Fix** - expand disk and filesystem; free `/opt/pram/images`; retry Convert & add or Bulk; for VMDK/OVA in staging use **Convert selected** after Scan.

## SCP Permission denied on staging

**Check** - SSH as `vexnx` (not GUI admin). Paths under `/opt/vex-nx/staging/...` should be mode `0777`.

**Fix** - `sudo systemctl restart pram-api` (ExecStartPre recreates and chmods drop zones). Or re-run first-boot / install. GUI Convert & add uses `/opt/pram/data/staging/upload` and `/opt/pram/images/staging/.incoming` as the API user (root).

## Assist LLM timeout or Test fails

**Check** - OpenRouter API key, selected model, network from appliance to openrouter.ai, host CPU. Assist is the lab **dock** (chips + cards), not Terminal float/wide.

**Fix** - fix or re-paste key; pick a catalog model (Claude Sonnet 5 default); retry **Test** from Administration. Without a key, Assist stays rule-based.

## Nested ESXi / vJunos Start fails with KVM error

**Check** - Infrastructure shows KVM; `/dev/kvm` on guest; nested virt exposed on Workstation or ESXi host VM.

**Fix** - Power off VEX-NX VM -> enable VT-x/EPT (or Expose HV to guest on ESXi) -> power on. Nested ESXi and vJunos require KVM (TCG not supported for those profiles).

## Licence import rejected

**Check** - you imported the **signed** licence, not the activation request; appliance ID matches; not expired.

**Fix** - export a fresh activation request; re-issue licence; import again.

## Console blank or node stuck booting

**Check** - node status; nested virt for QEMU; image in Library and not quarantined.

**Fix** - Wipe + Start; reopen Terminal; for IOSv without KVM, expect long boots or enable KVM.

## Student cannot see a lab

**Check** - share list; role; they are signed in as the expected user.

**Fix** - re-share from Classroom; confirm User role, not a typo account.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vex-nx.com/vex-nx-user-guide-1/reference/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.