Troubleshooting

The library or CLI cannot reach the service

vz service status

If nothing answers, open MacVisor: at launch it detects a LaunchAgent that is installed but not answering and re-registers it against the copy you are running. That fixes the common cause — a differently signed build replacing another (a notarized release over a development build, or the reverse), which macOS kills at spawn before it can log anything.

Otherwise use the dashboard's Control Service panel to restart it, or Assistant → Restart Control Plane Service. The Logs menu opens the service, app, or per-VM runner log; a VM runner can fail independently without stopping other VMs.

A storage location says it is waiting for permission

macOS requires consent before a background service reads removable, network, or otherwise protected folders, and blocks the read until the prompt is answered.

1. Click Allow in the macOS dialog when it appears.
2. Or open System Settings → Privacy & Security → Files and Folders and allow MacVisor Background Service — the sidebar has a button that opens it.
3. The VM runner asks separately the first time a VM stored there starts. Allow that too.

vz service status        # lists pendingStorageRoots while access is missing

Until it is granted the location shows as waiting rather than empty, so a pending prompt never looks like lost VMs.

Installation media will not boot

• macOS guests require a compatible IPSW and Apple Silicon.
• Linux media must be ARM64, not x86_64.
• Confirm the ISO remains attached during installation and is ejected afterward.
• Ensure the storage location has enough free space.

Guest tools stay disconnected

1. Confirm Guest Tools is enabled in VM Settings → Sharing, and that the VM has the Guest Agent Channel (vsock) device under Advanced.
2. In a macOS guest, make sure the agent was dragged into Applications and opened from there. An agent opened from the mounted volume shows copy instructions and quits — the volume is rebuilt each boot, so nothing installed from it would survive.
3. Check the guest's Login Items & Extensions for MacVisor Agent and turn it on if macOS is holding it for approval.
4. In a Linux guest, re-run sudo ./MacVisorGuestLinux/install.sh and check the systemd unit.

If two copies of the agent are running in the same guest, only one can hold the agent's ports. The agent quits rival copies at launch and reports a bind failure instead of appearing to work; the VM's Overview tab shows the same state on the host side.

Agent communication does not require ordinary guest network access.

The VM has no network

For NAT, verify the host is online. For bridged mode, confirm the selected physical interface still exists and the LAN permits new devices. For custom networks, verify the named network is available and the VM NIC points to it.

Port forwarding does not connect

Guest tools must be connected, the guest service must listen on the target port, and the host port must be unused. Check with vz ports list <vm> and vz ip <vm>.

Network-level forwards on a custom network are different: they need no guest tools, but they are fixed while any VM is using the network. Stop those VMs, edit the rules, then start again.

Firewall rules do not take effect

• The apply button is disabled — the network has no subnet yet. Start a VM on it once, or pin an IPv4 subnet in the network's addressing settings.
• The helper is waiting — open System Settings → Login Items & Extensions and turn MacVisor's network helper on.
• Traffic between two VMs is still flowing — that is expected. VM ↔ VM traffic on the same network is switched inside vmnet and never reaches the packet filter. Separate the workloads onto different networks.
• IPv6 traffic is unaffected — the firewall is IPv4 only.
• Nothing matches — open Show Active Rules… and read the per-rule counters. sudo pfctl -a 'com.apple/900.macvisor.firewall' -sr shows the same thing in Terminal.

vz is not found in Terminal

The /usr/local/bin/vz symlink is created by the network helper during first-run setup. If you declined the administrator prompt, the CLI still runs from inside the bundle:

/Applications/MacVisor.app/Contents/Helpers/vz list

Enabling the helper later — from the dashboard, or the first time you apply firewall rules — links it.

Converting a disk to ASIF is refused

• The VM must be stopped, with no suspended session and no layered (linked-clone) disk.
• Conversion writes a fully allocated image, so it needs the disk's declared capacity in free space, not just the space the guest uses. MacVisor says how much it needs.

VMs did not come back after a reboot

Check the dashboard's Unattended Auto-Start panel. Each link is reported live: the background service must be enabled, automatic login must be on, sudo pmset autorestart 1 covers a power cut, and FileVault holds the boot at the unlock screen until someone types the password. See Always-on host.

A live snapshot cannot resume

MacVisor can restore live memory only when the VM's current virtual hardware matches the captured configuration. If CPU, memory, disks, NICs, displays, or devices changed, revert the disk and start the VM normally.

A VM refuses to be deleted, reverted, exported, or templated

It is part of a linked-clone chain. A VM other VMs were forked from cannot be deleted or reverted until those clones are gone; a linked clone itself cannot be exported, templated, or full-cloned because part of its disk lives in the VM it was forked from. MacVisor names the VMs involved. See Linked clones.

Storage usage looks larger than expected

Logical size, physical allocation, and private size answer different questions. APFS snapshots and clones share blocks, so summing physical sizes can over-count actual unique storage. Use Private Size to estimate reclaimable space.

An external VM location disappeared

Reconnect and mount the volume, then refresh the library. Do not recreate or import the same VM while its original location is merely offline; that can produce confusing duplicate identities.

License activation fails

Copy the complete key from the receipt without extra spaces and confirm the Mac can reach the licensing service. If the license was issued for a different Mac, MacVisor says so and shows the Machine Code under Settings → License → This Mac; send it to us and we will reissue.

Sending us a problem report

Logs → Report a Problem… collects the app, service, and runner logs plus a summary of this Mac's MacVisor state into one zip, saved wherever you choose. Attach it to your email — nothing is uploaded on its own.