Skip to content

Limits and troubleshooting

Known limits

  • x86-64 only. The VM and machine images are x86-64.
  • Idle stop ignores services. A machine stops after idle_timeout minutes without nsl commands, editor sessions or windows, even if a service inside it is busy. Set idle_timeout = 0 to keep machines running.
  • No file events from the host. Host edits to files shared through /mnt/host produce no inotify events in the machine. Keep projects that need file watchers in the guest home.
  • No automount triggers. An unmounted host automount point appears empty in machines until the host mounts it.
  • Wayland only. Machines have no X server, so X11-only applications open no windows.
  • Host loopback only. Forwarded ports bind 127.0.0.1 on the host, and one port serves one machine at a time.
  • Archives are unencrypted and can contain credentials. Import requires your UID and GID.
  • Your whole home is visible to machines that are not isolated, including nsl's state and keys. This matches the trust model.
  • Data disks only grow. There is no shrinking.

Troubleshooting

nsl doctor fails
A tool, the UEFI firmware, a device or a permission is missing, or systemd is older than 259. Install the tool or firmware with your host's own tools; MISSING systemd 259 or newer needs a newer host release. If doctor reports MISSING kvm group membership, ask an administrator to run the displayed command to add you to kvm, then retry nsl; no new login is needed. nsl changes none of these itself.
Bare nsl fails and lists machines
There is no default machine, for example after removing it. Run nsl default NAME, or nsl -m NAME.
nsl run refuses to run
The current directory is not in a shared tree, or the machine is isolated. Pass --cd with an absolute guest path.
A port is not reachable from the host
Run nsl ports. A conflict means something else holds the port, on the host or in another machine. The server must listen on port 1024 or above, and not on 5353 or 5355.
A window does not appear
Check that nsl doctor finds Waypipe, that the command ran from a Wayland session, and that the machine is not isolated. nsl logs NAME shows the desktop session.
The VM does not become ready
Run nsl logs for the VM's messages, then nsl recover. Recovery starts the VM from a fresh root and keeps your machines.
A new setting has no effect
Resource changes apply at the VM's next start. nsl config shows what is pending; nsl shutdown applies it at the next command.
nsl reports Failed to connect to bus
nsl runs each VM as a user systemd unit, so the shell it runs in must reach your user systemd manager. A shell from su, sudo -u or a plain ssh without a login session can lack XDG_RUNTIME_DIR. Log in as that user, or set XDG_RUNTIME_DIR=/run/user/$(id -u) in the shell. When XDG_RUNTIME_DIR is set but nsl finds no bus or systemd/private socket in it, check that it is /run/user/$(id -u). If the path is correct, your user systemd manager may be stopped: log in to start it, or run loginctl enable-linger to keep it running.

Problem records

A release build of nsl writes 1 entry to your local systemd journal when it panics, and when it meets 1 of 4 internal errors, states its own code should never reach:

Code When
state.vm_record_invalid A VM record does not decode, does not validate, or is in the wrong place.
state.machine_record_invalid A machine record does not decode, or does not match its name and your identity.
vm.exited_on_start The VM's unit ended while nsl started it.
vm.readiness_timeout A started VM did not become ready in time.

The entry holds nsl's app ID (org.frostyard.nsl), its version, the error code or the panic's function names, and the error or panic message. Function names carry no source file paths, line numbers or arguments. The entry changes no command output and no exit status. A panic still exits 2 with Go's panic output, which now also shows [recovered, repanicked].

nsl sends nothing over the network. chairlift's Problems page can show the entries, and only chairlift sends a report, after you turn reporting on there. To catch a crash that no panic handler sees, each nsl process keeps a small crash file in frostyard-problems/org.frostyard.nsl under $STATE_DIRECTORY (set for systemd services), else $XDG_STATE_HOME, else ~/.local/state. After a crash the file holds Go's full crash report as printed on stderr; the next start turns it into 1 filtered entry and removes the file. With no journal, nsl drops each entry silently; the crash file is still kept. Builds from source with make record nothing.

To read the entries: journalctl --user MESSAGE_ID=8915bdd215c84cbab0c31c05a1a33e7e FROSTYARD_APP_ID=org.frostyard.nsl.

Report a problem

If you're still stuck, open an issue at github.com/frostyard/nsl ↗. Include what you tried and the output of nsl version and nsl doctor. Add nsl logs when it helps explain the failure.