Troubleshooting

When a VM fails to start, the library and the command line show the reason its process gave. The full story is in two files in the VM's folder (Show in Finder in its … menu):

• runner.log: what the VM's process said, errors as error: … lines. Emptied at each start.
• console.log: what the guest wrote to its serial console. Emptied at each start.

The VM doesn't start

“The process doesn’t have the “com.apple.security.virtualization” entitlement.” The binary isn't signed with Elyra VM's entitlements. The app built by scripts/bundle.sh is; a binary built with a plain cargo build is not. Use cargo run, which signs first, or sign it:

codesign --force --sign - --entitlements resources/ElyraVM.entitlements target/debug/elyravm

“Windows VMs from Parallels can't be imported yet.” Make a new Windows VM in Elyra VM (Windows guests).

“The installer … is not there any more.” The ISO the VM was made from has been moved or deleted. Put it back, or point installer in the VM's config.json at its new place, or remove the line if the system is installed.

“The VM’s configuration is not valid.” The framework refused the hardware: the rest of the message says what. Typical causes are a corrupt nvram or machine-identifier (delete the file; the VM makes a new one, though a saved state then no longer fits) or a shared folder that doesn't exist.

“This Mac does not support virtualization.” Elyra VM needs a Mac with Apple silicon, running macOS itself rather than inside a VM.

The VM's window opens, but stays black

• The ISO may be for Intel (x86_64). Linux ISOs must be for ARM64 (aarch64).
• A VM made from the catalog has nothing to boot yet (Creating VMs).
• After installing, the boot entry may be missing: check console.log, and boot the installer again to repair it.

macOS won't install

“Apple’s newest macOS could not be looked up.” The Mac couldn't reach Apple. Check the connection and start the VM again.

“macOS could not be downloaded. …” The download failed five times in a row. What was downloaded is kept; start the VM again to carry on.

“This Mac can’t run macOS … in a VM.” The version is newer than what this Mac's Virtualization framework supports. Use an older IPSW, or update macOS on the Mac.

“macOS … needs at least N processors and M of memory.” Give the VM more in its settings, then start it again.

“The macOS installer could not be read.” The IPSW is damaged. A downloaded one is deleted, so the next start downloads it again; replace one you chose yourself.

“macOS … could not be installed. …” Apple's installer failed. Start the VM again to install from the beginning. Downloaded IPSWs stay in ~/Library/Caches/Elyra VM/Restore Images/ (delete them there to free the space).

A Linux download fails

“The installer could not be looked up. …” Ubuntu's or Fedora's server couldn't be reached, or no longer lists that version. Check the connection, or make the VM from an ISO.

“The download of … is damaged, and was thrown away.” It didn't match the SHA-256 the distribution publishes. Start the VM again to download it again.

The VM restarted after I shut it down. A Linux VM that stops with its installer in and a system on its disk is taken to have just been installed, and starts again without the installer (Linux guests). Shut it down again; it stays off.

A suspended VM won't carry on

“… could not carry on from where it was saved” means the saved state no longer fits the VM, for example after its hardware changed outside the library, or after a macOS update. Start Afresh boots it cold; what was open in it when it was suspended is lost.

The VM won't shut down

Shut Down asks the guest, and a guest without systemd or acpid ignores it. Use poweroff in the guest or Force Stop.

The library shows the wrong state

The library asks each VM's process every 0.6 seconds. If a VM's process hangs, the library keeps the last state it knew. A VM whose process crashed shows as stopped (or suspended, if it was saved before); a stale runner.lock is harmless, as the lock is released with the process.

To see what each VM's process says, on the command line:

elyravm list
elyravm status "<vm>" --json

Clipboard, shared folders and display

• Copy and paste doesn't work: install spice-vdagent in the guest and log in to a graphical session; check "clipboard": true in the VM's permissions.
• Shared folders aren't there: mount the elyravm tag (Linux guests); the VM must be restarted after shared_folders changes.
• The display doesn't follow the window: the guest needs a desktop that handles virtio-gpu resizing; a text console keeps its size.

Elyra VM Tools doesn't answer

The VM's settings say Not running in this VM, status --json has "tools": null, or exec says Elyra VM Tools isn't running.

• It takes a few seconds after the guest has booted; the VM tries every 5 seconds.
• Is it installed and running? In the guest: systemctl status elyravm-tools. Its log is journalctl -u elyravm-tools; vsock port 1024 can’t be opened means the kernel lacks vsock for virtio (sudo modprobe vmw_vsock_virtio_transport).
• A system ready to use from the catalog installs it at the first boot. If it didn't come up, look in the guest's /var/log/cloud-init-output.log, or the VM's console.log. Log in at the console with the user and password in the VM's settings.
• exec or cp say Elyra VM Tools is too old: the agent is from 0.9.0, which can't update itself. Install it again in the guest (Elyra VM Tools).
• runner.log says it could not be updated: the reason follows; the VM tries again at its next start.

Starting over with a VM

With the VM stopped, these files in its folder may be deleted safely:

Never delete config.json or disk.img: they are the VM.