> For the complete documentation index, see [llms.txt](https://docs.layeronecloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layeronecloud.com/pve-microvm/troubleshooting.md).
# Troubleshooting
Source project: `pve-microvm` (migrated from `docs/troubleshooting.md`). Run commands from the code checkout and directory specified below, not from this documentation repository.
## "option 'X' is not supported with microvm machine type" --delete
```
Common: `bios`, `efidisk0`, `usb0`, `hostpci0`.
## "microvm requires a kernel" --args '-kernel /usr/share/pve-microvm/vmlinuz -append "console=ttyS0 root=/dev/vda rw"'
```
## No console output ` (not noVNC)
4. Press Enter — the shell may be waiting for input
## Kernel panic: "No working init found" i0`
3. Inside guest: `ip link` — may need DHCP or static config
4. Try: `udhcpc -i eth0` (Alpine) or `dhclient eth0` (Debian)
## "KVM virtualisation configured, but not available" --pretty | grep -E 'qmp-event|qmeventd.sock'
```
Existing Debian/Ubuntu guests built without D-Bus also need:
```bash
qm guest exec -- bash -lc \
'apt-get update && apt-get install -y dbus && systemctl enable --now dbus'
```
Then verify both lifecycle operations. A reboot must change the guest boot ID; a shutdown must leave no QEMU process behind:
```bash
qm reboot
qm shutdown --timeout 60
qm status
```
Guests created with `--no-agent` still have no guaranteed graceful shutdown path; use `qm stop` or install/enable the QEMU guest agent.
## Patches not applied after qemu-server upgrade --machine microvm --memory 256
pve-oci-import --image alpine:3.21 --vmid
```
## Linked qcow2 clone drops into the initrd or BusyBox --pretty | grep 'drive-scsi0'
```
A file-backed qcow2 clone must include `format=qcow2`; LVM-thin and ZFS block volumes normally use `format=raw`. Releases before v0.3.23 could call a nonexistent PVE format API, swallow the error, and pass a qcow2 overlay as raw. Do not rename the image or change `root=/dev/vda` as a workaround.
With cloud-init, the supported order is:
```
scsi0 -> /dev/vda root filesystem
scsi1 -> /dev/vdb cloud-init data
```
Collect `qm config`, `qm showcmd --pretty`, `pvesm status`, and `PVE::Storage::parse_volname()` output when diagnosing a backend-specific format mismatch.
## No network / no guest agent / no balloon --pretty | grep -E 'virtio-(net|serial|balloon)'
ls -l /dev/vport* /dev/virtio-ports/*
```
A `/dev/vport*p*` character device proves that the virtio-console driver is active. Do not expect a particular number: the index follows virtio probe order, and a trixie guest on PVE 9.1.9 gets `/dev/vport2p1`. The named `/dev/virtio-ports/org.qemu.guest_agent.0` symlink additionally depends on guest udev processing and is absent on these guests even though the kernel driver works.
Since v0.3.24, generated systemd guests use one replacement unit named `qemu-guest-agent.service`. It polls for the named device and then for any `/dev/vport*p*`, and starts the packaged agent directly against the first match, avoiding the missing-symlink failure, the hardcoded-index failure, and the older competing-agent restart loop. Diagnose existing guests with:
```bash
systemctl status qemu-guest-agent.service microvm-agent.service --no-pager
ps -ef | grep '[q]emu-ga'
ls -l /dev/vport* /dev/virtio-ports/*
```
There must be exactly one `qemu-ga` process. See `docs/known-issues.md` for the existing-guest replacement unit and EL binary-path note.
The release workflow prints the final values of `CONFIG_VIRTIO_NET`, `CONFIG_VIRTIO_CONSOLE`, and `CONFIG_VIRTIO_BALLOON` after `olddefconfig`; all must be `=y`. The overlay is in `kernel/pve-microvm-overlay.config`.
---
# 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.layeronecloud.com/pve-microvm/troubleshooting.md?ask=&goal=
```
`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.