Troubleshooting

These are setup and lifecycle problems supported by the current repository. The application cannot install a guest operating system, manage installation media, or configure networking yet, so those missing features are not troubleshooting issues.

Missing Tauri system libraries

If cargo check or npx tauri build fails while looking for WebKitGTK, GTK, or libsoup, install the Tauri 2 Linux prerequisites. On Arch Linux the relevant packages are webkit2gtk-4.1, gtk3, and libsoup3. Package names differ by distribution.

cargo check --manifest-path src-tauri/Cargo.toml

Run the failing command again after installing the libraries. The Rust check requires them even if you only want to inspect the frontend.

The frontend opens in a browser but commands fail

The frontend is static and expects the Tauri desktop shell. Opening src/index.html directly, or serving it with a generic static server, does not provide the Tauri command bridge. Use npm run dev from the desktop repository.

Machine creation is rejected

The backend requires a Linux x86_64 host and an x86_64 guest. It also validates the machine name, memory, virtual CPU count, and disk size against fixed limits and the host's reported memory, CPU count, and free space. Read the error returned in the dialog; the backend does not silently correct invalid input.

• Name: up to 64 characters; no control characters or /, \, comma, or equals characters.
• Memory: 256 to 65,536 MiB, and no more than host memory.
• Virtual CPUs: 1 to 64, and no more than the host's logical CPU count.
• Disk size: 1 to 1,024 GiB, and no more than free application-data space.

QEMU or qemu-img is reported as missing

QEMU and qemu-img are required for VM operations. Install a QEMU package that provides the system emulator for your host architecture and qemu-img, then make sure the executables are on PATH or in a location the discovery code checks. Re-run host diagnostics after installation.

qemu-system-x86_64 --version
qemu-img --version

Use the emulator name that matches your architecture if it is not qemu-system-x86_64. The shell can still start without QEMU, but a machine cannot be created or started.

QEMU is found but the probe fails

The discovery code runs the executable with a version flag and applies a five-second timeout. A file that exists but cannot execute, a broken installation, or an executable that hangs will produce a probe failure. Run the version command above in a terminal to see the underlying error.

KVM is missing or inaccessible

On Linux, check whether the device exists and whether your user can access it:

ls -l /dev/kvm

A missing device usually means the host kernel or virtualization support is not configured. A permission error means the current user cannot open it. Follow your distribution's documented KVM setup; do not run Wave VM as root, and do not expect Wave VM to change device permissions or group membership.

KVM is optional. If it is unavailable, QEMU falls back to software emulation (TCG). The machine can still run, but it may be slow.

A machine will not start

Check the error shown by the application and the QEMU log for that machine. The log is stored at vms/<machine-id>/qemu.log under the application data directory. Common causes include a missing disk file, a QEMU launch failure, a stale QMP socket that another process is still using, or a QEMU build without the required features.

Wave VM blocks a duplicate launch when it detects a live QMP endpoint for the machine. If a QEMU process was left behind by a force-killed desktop process, close that process before trying again. Do not delete a VM directory or disk to work around a lifecycle error.

The console will not connect

The console is available only while the machine is running. It requires a QEMU build with WebSocket VNC support. If QEMU starts but the console reports that no WebSocket listener was found, check the installed QEMU version and its VNC support. The console is bound to 127.0.0.1 and uses a password generated for the current run.

A new machine has a blank disk. If no guest operating system is installed, the console may show firmware output or a no-bootable-device message rather than an operating system. That is expected in the current milestone.

Configuration errors

Configuration failures are reported with explicit error codes, including config_path_unavailable, config_directory_failed, config_read_failed, config_parse_failed, config_invalid, config_version_unsupported, and config_write_failed.

Check that the application data directory is writable by your user. Do not delete or overwrite existing user data to work around a permission problem. See Storage and configuration for the expected files and permissions.

No download or installer

There is no public release artifact. If you found an installer that claims to be an official Wave VM release, treat it as unverified. The only supported way to inspect the current build is to build from source.

Windows and macOS

The current environment has only exercised Linux x86_64 host behavior. macOS and Windows behavior is unverified. Do not assume that a successful compile on another platform means host diagnostics, KVM/WHPX/HVF detection, VM creation, or VM execution are supported.