Troubleshooting

Find your symptom below. If nothing here helps, send us a problem report.

Service and app

The library or CLI cannot reach the service

mvz exits with status 4 when the background service can't be reached at all, and 5 when it is busy and doesn't answer in time. After a 5 the service may still be doing what you asked, so check mvz tasks first.

1. Run mvz service status.
2. If nothing answers, open MacVisor. It re-registers the service and, if macOS needs your approval, shows a sheet and opens System Settings → General → Login Items & Extensions.
3. Under Background App Activity, switch MacVisor on. If it is already on, switch it off and on again. This is usually needed after a differently signed copy of MacVisor was installed over this one, such as a development build followed by a release.
4. Otherwise restart the service: the dashboard's Background Service panel, Assistant → Restart Background Service, or mvz service restart. Work in progress, such as a clone or an export, finishes first: mvz service restart names it and asks (--yes in a script; --cancel calls a waiting restart off).

Logs are under the Logs menu. mvz service logs --tail 200 shows the service log. Each VM's runner log is ~/Library/Application Support/MacVisor/logs/<VM id>-runner.log. On a Mac you reach over SSH, see On a Mac you reach only over SSH.

If the service answers but the library doesn't load, for example while an external disk spins up, the sidebar shows Couldn't load your library with the reason and Retry. MacVisor also retries on its own.

MacVisor says the background service is still starting

The service can take a minute to start after the Mac boots. MacVisor shows "MacVisor's background service is still starting…" instead of errors, and restarts the service only if it stays silent for two minutes.

After a macOS update, the first start can take several minutes while macOS re-indexes the disk. Don't quit MacVisor or toggle it in Login Items. Let it finish and the window fills in. Running VMs aren't affected. If it still doesn't answer, see The library or CLI cannot reach the service.

mvz says the service is still running an older MacVisor

The service keeps running the build it started with until it restarts. Open MacVisor, or run mvz service restart. Running VMs keep running.

A VM started before the update keeps its old runner. If an action says the VM "can't do this yet", shut the VM down and start it again.

If mvz service status says network changes finish once every VM on a custom network has been stopped and started again, stop all the VMs it names, then start them. Restarting them one at a time keeps the old network process. See After an update.

mvz is not found in Terminal

The /usr/local/bin/mvz link is made by the network helper. Switch the helper on, then use Assistant → Setup Assistant… → Command-Line Tool. Until then, run the binary directly:

/Applications/MacVisor.app/Contents/Helpers/macvisor-cli list

Starting and running VMs

A VM is busy, or still open in another runner

• "dev" is busy: exporting. Long work (export, move, suspend, snapshot, disk conversion, flatten) blocks other actions on that VM. Try again when the task pane or mvz tasks shows it finished. Power Off never waits.
• "dev" is still restoring its saved session. A start or resume is reading the saved memory back, which can take minutes for a large VM on a slow drive. Power Off can't stop it meanwhile. Try again when the restore has finished, or wait for the start to time out.
• "dev" is still open in another MacVisor VM Runner. A runner from an earlier start still holds the VM's disks. Wait a moment and start again, or run mvz poweroff dev to end it.

A VM won't start, or stopped with an error

The alert's title says what failed, such as Couldn't Start "dev", and its message names the cause. Beside OK it may offer one way forward:

• Open VM Settings when something the VM's settings name is missing, such as a disk image, installer, shared folder or network, or when the VM has more CPUs or memory than this Mac allows, as a VM from a bigger Mac can.
• Show Logs when the VM's runner log says why. Every runner log is also under Logs → Runner Logs.
• Try Again when the connection to the background service broke before it answered.

Common causes are a disconnected drive or a full disk. Reconnect the drive or free space, then start the VM again.

When a start, stop or other VM action you asked for fails, the main window comes forward with the alert, also when you used the menu bar item with the window closed. If MacVisor isn't the app in front, a notification says what failed as well.

A suspended VM won't resume

Usually the Mac's screen is locked. macOS restores a saved session only while you are logged in at the Mac with the screen unlocked.

1. Unlock the Mac, or connect with Screen Sharing.
2. Resume again. A VM set to start at login resumes by itself after you unlock.

Otherwise the VM's Overview says why and offers Try Again and Start from Disk… (mvz show <vm> says the same). The most common cause is an update of macOS or of MacVisor, after which the session can't be restored. Another is a writable disk image, attached in VM Settings → Storage, that changed while the VM was suspended: resuming could damage what's on it now, so MacVisor won't. Starting from disk drops the saved session and boots the disk as it is. Nothing on the disk is lost.

mvz start <vm> --discard-state

Settings you changed while the VM was suspended don't cause this. They apply after the next shutdown.

Suspend is refused or fails

Suspending writes the VM's memory to disk. MacVisor refuses up front when there clearly isn't room, and says how much is needed. If a save runs out of space anyway, the VM keeps running. Free space and try again, or shut the VM down.

A suspend or live snapshot is also refused when a guest tools disc you attached while the VM runs can't be ejected: a saved session can't hold it. Eject it with Eject Guest Tools or mvz tools eject <vm> and try again, or shut the VM down.

A live snapshot cannot resume

Live memory restores only on the virtual hardware it was saved with. A revert puts back the snapshot's settings with its disks, so later hardware changes are undone. After a macOS or MacVisor update, the VM boots from the snapshot's disk instead. For a locked screen, see A suspended VM won't resume.

A VM paused by itself

The drive its disks are on had less than 2 GB free. MacVisor pauses every VM writing to that drive, so nothing more is written, and tells you; it warns earlier, below 10 GB. It never resumes them itself: free up space (empty the Trash, where replaced disks and deleted VMs go), then resume the VM in the app or with mvz resume <vm>. See When a drive gets full.

VMs did not come back after a reboot

1. Check the dashboard's Unattended Auto-Start panel. It needs the background service enabled, automatic login on, sudo pmset autorestart 1 for power cuts, and FileVault off or someone present to unlock.
2. Check the task pane or Task History. Each auto-start is listed with its result.
3. VMs shut down at logout boot fresh. To have them resume, choose Suspend VMs in Settings → General → Logout and Shutdown.

See Always-on host.

Hooks and restarts

A hook doesn't run, or fails

Read the VM's hooks log, ~/Library/Application Support/MacVisor/logs/<VM id>-hooks.log, and run the hook's Test. Hooks have their own PATH, no ~/.zshrc and no SSH agent, and a hook that touches Desktop, Documents or Downloads waits for macOS to ask whether MacVisor may. When no hook runs for any VM, the hooks file can't be read, and VM Settings and mvz hooks say why. See When a hook doesn't do what you expect.

Shut Down pressed the power button instead of the shutdown command

Tasks says why, such as The shutdown command failed (exit 255: Connection refused); pressed the power button instead. Run the command in Terminal to see what it prints. See The shutdown command.

A VM restarted by itself

Tasks says who did it: Restarted by high availability after a crash, an error or a failed start, or Restarted "web" with a health check's or VM Watchdog's reason. The VM's hooks log has the evidence of the latter. See A VM restarted by itself.

The Overview says Guest screen not responding

A macOS guest's WindowServer has stopped answering the MacVisor Agent, while SSH and the rest of the guest still work. See Guest screen not responding.

Installing guests

Installation media will not boot

• macOS needs a restore image (.ipsw) for virtual Macs on Apple Silicon. MacVisor checks this when you add it.
• Linux media must be ARM64, including cloud images you add.
• Windows must be Microsoft's Windows 11 on ARM ISO. x86 ISOs are refused.
• Keep the ISO attached during installation and detach it afterwards (mvz set <vm> --iso none).
• Check free space in the storage location.

A Debian or Kali install fails at partitioning

Debian's installer, which Kali uses too, can't format its EFI system partition on a disk with 4 KB sectors: partitioning fails and the installer stops. Make the VM again with Sector Size at 512 bytes, the default, or mvz create <file.iso> <name> --os linux without --sector-size 4096. A disk's sector size can't be changed. See Debian and Kali installers need 512-byte sectors.

A macOS install is in the way, or was interrupted

While macOS installs, MacVisor refuses to start, change, clone, export, snapshot or delete the VM. Wait, or cancel with Cancel Task in the task pane (mvz tasks cancel <task-id>).

A cancelled or failed install leaves the VM stopped, with the reason in the task pane and mvz tasks; mvz show <vm> says "Last install: didn't finish" until an install or start succeeds. Use Erase and Install macOS… (mvz reinstall) to try again, or delete the VM.

If the install says MacVisor can't open the IPSW in Downloads, macOS is keeping MacVisor out of that folder. Move the file to another folder, or add it with the + in Templates (mvz images add <file>), then install again.

Creating a Windows VM seems to do nothing

The first Windows VM on a Mac waits for its drivers, about 1 GB, before it's made. Its row is in the list meanwhile, with "Downloading the Windows drivers" and the download's progress; Tasks shows the download as "Get the Windows drivers (virtio-win)", and mvz tasks lists it. Keep MacVisor running and the Mac online until it finishes: the VM then takes the row's place and its install starts. A download interrupted by a dropped connection or a restart carries on where it stopped. Later Windows VMs reuse the drivers and start at once.

Windows VMs are tested on macOS 27.2 and later. On an earlier macOS, the New VM form warns that Windows may not install or start.

A Windows install failed, hangs, or was cancelled

Setup takes about 10 minutes. The window sitting on the Windows logo for a few minutes between boots is normal. --ssh installs OpenSSH Server from a release MacVisor downloads with the drivers; when that download isn't available, the setup adds it from Windows Update instead, which takes about 10 minutes more and needs network access.

To stop an install, use Cancel Install… in the VM's menu, Cancel Task in the task pane, or mvz tasks cancel <task-id>. A failed or cancelled install leaves a stopped VM you can delete.

When the copy onto the disk fails, the task's error ends with the installer's log, and the full logs are kept in the VM's bundle as windows-install.log and windows-dism.log. When Windows installed but a setup step failed (shared folders, OpenSSH Server, the agent...), the task reads Installed, with warnings and names the component; the guest's log is C:\ProgramData\MacVisor\setup-complete.log.

A download stalled, failed, or was cancelled

Downloads resume. Run the same mvz images pull or mvz create again and it continues from where it stopped. A download interrupted by a service restart resumes on its own. One you cancelled stays stopped until you pull it again. Partial files left alone are removed after two weeks.

• Not enough space. A download that won't fit is refused before it starts, with how much to free. One that fills the disk anyway keeps what it got. Free space and pull again.
• Checksum failure. The file is discarded. Pull again. For "latest" catalogue entries the checksum comes from the vendor at download time, so a vendor outage shows up as a failed check.

A VM in the list says Couldn't be created

A VM being made failed before it was made: its download failed, or it finished and making the VM failed (not enough space, a refused restore image). Select the row: its card says why, with the background service's reason under it. Fix the cause, then click Try Again, or create the VM again with New VM. Try Again is there also for a create from mvz create or from before the app was opened again, except one with a password you chose yourself or cloud-init user data of your own, which MacVisor doesn't keep: that row offers Remove alone, and you create the VM again. Remove takes the row out of the list and deletes nothing; a download that finished stays for the next VM. If the card says the background service restarted before the VM was made, the download carries on by itself: try again once it has finished. See While a VM is being made.

A Linux VM's setup reported errors

The VM's Overview says Setup reported errors, with what failed in one line. Show Log shows cloud-init's errors and the end of its output. The VM's runner log (Logs → Runner Logs) has them too, so a problem report carries them, and /var/log/macvisor-setup.log in the guest has MacVisor's part of the setup in full.

MacVisor's own steps, the agent, a container runtime and Ubuntu Desktop, run again at each start until they succeed. A runtime and Ubuntu Desktop are installed from the internet, Ubuntu Desktop from Ubuntu's archive and the Snap Store, so the VM must reach them. Fix the cause, then restart the VM.

If the Overview says Setup hasn't reported, the guest agent hasn't connected 10 minutes after the start, so setup may have failed before installing it. Show Console Log shows the guest's boot.

Guest tools and shells

Guest tools stay disconnected

1. Make sure Guest Tools and MacVisor Agent Channel (vsock) are on in VM Settings → Guest Tools (in a FreeBSD VM, Guest Tools only).

2. Cloud-image Linux VM: cloud-init installs the agent on first boot. mvz wait <vm> returns when it's done. A VM made with --no-agent has none.

3. macOS 27 guest with automatic setup: MacVisor installs the agent over SSH after the first boot. If the password changed, Remote Login is off, or MacVisor lacks Local Network permission, install it by hand.

4. macOS guest, by hand: drag MacVisor Agent into Applications and open it from there, not from the mounted volume. If macOS holds it for approval, turn it on in the guest's Login Items & Extensions.

5. macOS agent only runs when opened by hand: the copy in Applications doesn't match the one that registered the login item. Copy the agent from the current MacVisor Agent volume into Applications and open it once.

6. Linux guest installed from an ISO, or an appliance: attach the disc if it isn't in (Attach Guest Tools on the Overview), re-run the installer and check the macvisor-agent service:

   sudo mount -o ro -L MACVISOR_AGENT /mnt && sudo sh /mnt/install-linux.sh

7. FreeBSD guest: Enable Guest Tools must be on, and a VM made before must have been shut down once since you updated MacVisor. Click Install Agent on the Overview (if it says to restart the VM first, the VM resumed a session saved before it had its serial ports: shut it down and start it), then check service macvisor_agent status and /var/log/macvisor-agent.log in the guest. In a FreeBSD-based appliance, install it by hand from the disc. See The MacVisor Agent on FreeBSD.

Guest Tools says the agent is updating, or Not Trusted

From MacVisor 27.2.1 the agent must prove it is the VM's own before MacVisor sends it the clipboard, files or connections. See Agent authentication.

• Updating: the agent is from an earlier MacVisor, and MacVisor is updating it. Clipboard sharing, file transfer, port forwarding and mvz exec through the agent come back once it has.
• Outdated: an agent from an earlier MacVisor that MacVisor couldn't update itself, such as one you installed by hand in a macOS VM. Until it's updated it gets only what isn't private: the guest's details, shutdown and the update. Click Update Agent on the Overview; in a VM MacVisor didn't set up, drag MacVisor Agent from the tools volume into Applications again.
• Not Trusted: the agent couldn't prove itself, so MacVisor sends it nothing private, and the VM's runner log has a line starting Security:. Another account in the guest may be holding the agent's ports: check for processes you don't know. If you reverted the VM to a snapshot from before, or reinstalled the agent, click Update Agent on the Overview, which gives it the VM's key again.

mvz shell asks for a password or is refused

• Linux, "Permission denied (publickey)": none of your keys is authorised in the guest. The account has no password. Add your key to the guest's ~/.ssh/authorized_keys, or recreate the VM with --ssh-key. A VM made with --no-ssh-keys, or before your current key existed, has nothing to match.
• Linux, plain ssh or an editor fails but mvz shell works: the VM was made with MacVisor's own key, which only mvz uses. Make a key of your own (ssh-keygen -t ed25519) and authorise it.
• macOS: Remote Login must be on (--ssh at creation, or the guest's Sharing settings). The first connection asks for the account's password once, then uses your key. The default account is macvisor, with a random password made for each VM unless you chose one: mvz password <vm> prints it, and Copy Password on the VM's Overview copies it. VMs made before beta 6 use the password macvisor.
• Setup still running: shell connects before cloud-init finishes. Use --wait to hold until it's done.
• "Too many authentication failures": sshd stopped after too many keys were offered. mvz shell and mvz exec offer the keys the VM was made with, at most five, so this happens only when MacVisor doesn't know them: a VM made with --no-ssh-keys, keys added by hand, or a VM made on another Mac. MacVisor then offers its own key and the first of yours, and says so. Connect with the right key: ssh -i ~/.ssh/<key> -o IdentitiesOnly=yes <user>@<vm>.mvz.
• "isn't running", exit status 6: mvz shell and mvz exec no longer start a stopped VM for you. Start it (mvz start <vm> --headless), or add --start.
• Windows: a VM made with --ssh takes keys only. Its password is for the login window and Remote Desktop.

Type Password typed the wrong characters

• Check Keyboard in the VM in VM Settings > Keyboard & Pointer matches the VM's layout. U.S. is for a U.S. layout, the one Windows gets from an English (United States) ISO. Same as This Mac is only for a VM that uses your Mac's layout, and Mac and PC variants of a layout still differ on some keys, such as French punctuation.
• Caps Lock must be off in the VM.
• Use Show Password on the Overview and type it yourself.

Type Password typed nothing after an update

Right after an update, Type Password on the Overview can say MacVisor's background service still runs the version from before the update. Nothing was typed. Quit and reopen MacVisor, or use Type Password in the VM's window.

Type Clipboard typed nothing, or not all of it

• Some characters can't be typed: the alert names them, and nothing was typed. Check Keyboard in the VM in VM Settings > Keyboard & Pointer. A Windows, Linux or FreeBSD VM on Same as This Mac gets only letters, digits, spaces, tabs and line breaks unless your Mac's layout is U.S. or ABC; if the VM's keyboard is U.S., choose U.S. Otherwise use clipboard sharing or a shared folder. See Type Password and Type Clipboard.
• Keys were still held down: let go of Control, Shift and Command after the shortcut, then choose Type Clipboard again.
• The clipboard has no text to type: copy text, not a file or a picture. If macOS asked whether MacVisor VM may paste, allow it.
• Typing stopped after N of M characters: you switched to another window or app, or the VM paused or suspended. The characters before it arrived; copy the rest and type that.

Networking

No route to host

The VM has an address, but connecting to it fails with No route to host. macOS requires each app to have permission to reach the local network, and VMs live on one (192.168.64.x by default). Which app needs it depends on what connects:

1. Turn the permission on under System Settings → Privacy & Security → Local Network.
2. For MacVisor itself, open Assistant → Setup Assistant…. Its Local Network item shows what's missing. See Local Network.
3. If permissions are on, look for something that captures the VMs' range: a VPN that routes all traffic, a content filter, or a firewall on the VM's network that denies inbound traffic.

The VM has no network

• NAT: check that the Mac is online.
• Bridged: the interface must exist, and the LAN must accept new devices.
• Custom network: the network must exist on this Mac. A VM that arrived with an unknown network is moved to the Default MacVisor Network, and the service log says so. If every VM on a network lost it for about a minute, macOS stopped the network and MacVisor made it again: the Tasks pane shows Rebuilt network. See When macOS stops a network.
• Host-only with a fixed subnet: on macOS 27.2, VMs get no network link at all. Leave the subnet automatic. See Addressing.

Port forwarding does not connect

1. Check mvz show <vm>. It lists automatic forwards and why one isn't active, for example "the port is already in use on this Mac".
2. Check mvz ports list <vm> for forwards you added. UDP needs --udp.
3. Guest tools must be connected, and the service must listen on 127.0.0.1, ::1, 0.0.0.0 or :: in the guest. A service bound to one specific guest address isn't reached. If the Overview's Guest Tools says the agent is updating, or Not Trusted, forwards wait for it: see Agent authentication.
4. A VM's forwards are for this Mac only. From another device, use a custom network's port forwarding or a bridged network: see Reaching a VM from other devices. A forward 27.2.0 had on 0.0.0.0 or a LAN address now listens on 127.0.0.1.
5. Some ports are never forwarded automatically. See What automatic forwarding leaves out and forward those by hand.

http://<vm>.mvz:<port> doesn't use a forward. It goes to the guest's own address, so the service must listen on 0.0.0.0 and the guest firewall must let it in.

A network-level forward on a custom network is in force once the network is made again: click Apply Now… in the network's editor, which unplugs its running VMs for a few seconds, or wait until no VM uses the network.

<vm>.mvz doesn't resolve on a Mac with several accounts

The Mac's resolver sends every account's .mvz lookups to one port, 127.0.0.1:5380, and the first account to log in has its MacVisor answer them. Another account's VMs don't resolve by name while it is logged in. mvz service status and the Setup Assistant's VM Names on This Mac row say which account or program holds the port. Reach your VMs by address meanwhile (mvz ip <vm>); once that account logs out, your MacVisor takes the port within seconds. If another program holds the port, quit it.

A DHCP reservation is not honoured

• A reservation saved while VMs use the network waits until the network is created again: mvz networks and mvz show mark it waiting. Click Apply Now… in the network's editor, or run mvz networks apply <network>, to do that now.
• Reservations work only where macOS serves DHCP: shared networks, and host-only networks on an automatic subnet.
• On a shared network, a reservation holds only while the network keeps its subnet.
• MacVisor makes automatic reservations only for VMs it set up with cloud-init, and for macOS and Windows VMs. For an appliance or a Linux VM installed from an ISO or imported, make its DHCP client identify by MAC address and add a reservation by hand with mvz networks reserve.
• The guest must identify itself by MAC address. Cloud-image Linux VMs do; FreeBSD VMs don't, so reach them as <vm>.mvz. A hand-installed Ubuntu needs dhcp-identifier: mac in its netplan config.

See DHCP reservations.

Firewall rules do not take effect

The network's Firewall section, and mvz networks firewall <network>, say whether the rules are in force.

Other cases:

• A rule is skipped, or the CLI refuses every change. A rule that can't be enforced as written is skipped. The CLI refuses changes until you fix it in the app or drop it with --clear.
• Traffic between two VMs still flows. This is expected. VM-to-VM traffic on one network never reaches the packet filter. Use separate networks.
• A VM still has IPv6. VMs running when the firewall went on keep IPv6 until every VM on the network stops. The firewall is IPv4 only.
• Check what pf holds: sudo pfctl -a 'com.apple/900.macvisor.firewall' -sr

Creating or deleting a VLAN interface asks for a password

The network helper changes VLANs without a prompt only for an administrator account, and only deletes VLAN interfaces it created. Other cases get the macOS administrator prompt. See VLAN interfaces.

Windows guests

A Windows VM's display is garbled, black, or tiny

With Display: Apple (mvz set <vm> --display apple) the VM window shows Windows at 1024 x 768 only, and if Windows switches to another mode the screen goes black or sheared until the agent switches it back a few seconds after sign-in. Switch back to the default, Virtio-MVZ (mvz set <vm> --display macvisor), which takes any resolution and follows the window; the change applies at the next start from shut down. If the window still misbehaves, use Remote Desktop meanwhile, with Open in Windows App on the Overview tab or mvz rdp <vm>, and tell us. See The display.

Text that looks too small or too large comes from Windows' own scaling. The MacVisor Agent sets it to follow the pixel density (200% at Retina, 150% at Automatic in a large window, 100% at Standard) once for each Windows user and density; a scale chosen in Windows afterwards stays until the density changes. An agent from before 27.2.1 doesn't: set it in Settings → System → Display → Scale, or let MacVisor update the agent.

A Windows VM uses a lot of the Mac's CPU

Windows draws its desktop with the Mac's CPU, so the cost grows with the guest's pixels and with whatever moves on its screen.

1. In VM Settings → Display, keep Pixel Density at Automatic, which gives the guest at most 4K's worth of pixels. Retina in a large window on a 5K or 6K display draws far more. mvz show <vm> says which density a VM uses.
2. Turn on Reduce Visual Effects on the same page, or run mvz set <vm> --visual-effects reduced.
3. Pause video and animations you aren't watching. Two vCPUs instead of four cost the Mac a little less, at lower frame rates.

See What it's good for.

Remote Desktop can't reach a Windows VM

1. Make sure the VM is running and has an address (mvz ip <vm>). Remote Desktop answers about a minute after boot.
2. Give Windows App Local Network permission in System Settings → Privacy & Security → Local Network.
3. After a resume, the network needs the agent to come back. If the agent isn't connected, restart the VM.

FreeBSD guests

A FreeBSD VM's window shows no login prompt

The window shows FreeBSD's loader first, then its "FreeBSD is starting" note, and switches to the console when FreeBSD writes its login prompt there, about a minute into the boot. Console in the toolbar's Display | Console switch, or View → Show Console (⌃⌘C), shows it at any time. Sign in as your account with the password from Show Password on the Overview or mvz password <vm>; root can't sign in there. The first boot takes 2 to 5 minutes and needs network; the Overview shows Setting up FreeBSD until it's done, then Set up: ready for SSH.

A FreeBSD VM made with an earlier MacVisor has no login prompt: its guest was left as it was. Use SSH (Open in Terminal, mvz shell <vm> or ssh <vm>.mvz), or add one as FreeBSD VMs made before says.

Shut Down doesn't stop a Linux VM

Linux guests get the power button first, then, 15 seconds later, the MacVisor Agent's shutdown if nothing in the guest took the button, or a QEMU guest agent's when MacVisor's agent can't be asked. A program's shutdown lock is never overridden: release it (systemd-inhibit --list in the guest) and choose Shut Down again. A desktop that took the button may be asking on the guest's screen: open the VM's window. Choosing Shut Down again doesn't restart the 15 seconds. While the VM reads Stopping, which lasts up to 5 minutes after a shutdown the guest didn't act on, mvz shell and mvz exec wait. Without either agent, install one (in an appliance, a QEMU guest agent, if it offers one), enable acpid in the guest, or use Power Off.

Shut Down doesn't stop a FreeBSD VM

MacVisor tries MacVisor's agent, a QEMU guest agent, SSH, then the power button. FreeBSD ignores the button while its boot scripts still run, such as the first boot's package install or a background fsck, so MacVisor presses it again a minute later. If the VM still runs 30 seconds after that, the Tasks pane says so.

• Shut it down from inside: mvz shell <vm>, then sudo shutdown -p now, or at its console.
• Use Power Off (mvz poweroff <vm>) when nothing will be lost.
• A VM made with an earlier MacVisor acts on the button only from its next start from shut down.
• For the SSH step, MacVisor connects with its own key, so leave that key in the guest's ~/.ssh/authorized_keys, and give MacVisor Local Network permission (see No route to host).
• A FreeBSD-based appliance, such as a pfSense-based or OPNsense-based one, may not act on the button. Shut it down from its web UI or console.

Storage

A storage location says it is waiting for permission

macOS blocks the background service from reading removable, network or protected folders until you allow it.

1. Click Allow in the macOS dialog, or allow MacVisor Background Service under System Settings → Privacy & Security → Files & Folders. The sidebar has a button for this.
2. When the first VM stored there starts, the VM runner asks separately. Allow that too.

mvz service status lists such locations as Waiting for permission: <path>.

A VM on a network share can't be moved to the Trash

A network share has no Trash, so MacVisor refuses rather than delete the VM for good. Move the VM to another storage location and move it to the Trash there, or shut it down and delete its folder in Finder.

An external VM location disappeared

The location shows Offline in the sidebar. Reconnect the volume and refresh the library. Don't recreate or import the same VMs while the location is offline, or you will have duplicates.

A VM is listed as couldn't be loaded

The sidebar's couldn't be loaded list names the setting in the VM's config.json that stopped it, and its value. Usually the VM was made or changed by a newer MacVisor, which added that value (a network mode, container runtime or disk format). Update MacVisor to open it. A newer MacVisor's VM can't be opened in an older one, and an older one can lose settings it doesn't know when it saves the VM.

Two other reasons:

• Duplicate VM id: the package is a copy of a VM that is listed, such as a Finder duplicate, and the message names both paths. Import the copy to make it a VM of its own. See Copies of a VM.
• MacVisor couldn't read the mark that tells it this VM was made on this Mac: check that you can read the files in the .host-secrets folder inside the VM's package. MacVisor lists the VM again once it can, without resetting it.

Storage locations can't be added or changed

The list lives in ~/Library/Application Support/MacVisor/locations.json. If that file is damaged or was written by a newer MacVisor, MacVisor won't overwrite it and refuses changes. Restore locations.json.bak from the same folder, or fix the file, and try again.

Add Location refuses a folder

• Synced by iCloud or another cloud service: choose a folder outside iCloud Drive, Desktop & Documents (when iCloud syncs them) and ~/Library/CloudStorage, such as ~/VMs or a folder on another drive.
• The background service can't read it: allow MacVisor Background Service under System Settings → Privacy & Security → Files & Folders, then add the folder again.
• macOS is still asking: click Allow in the macOS dialog, then add the folder again.

A folder on a network share or a drive that isn't APFS gets a warning instead: Add Anyway adds it.

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

The VM is part of a linked-clone chain, and MacVisor names the VMs involved.

mvz flatten <vm> (stopped, no snapshots) makes a disk self-contained. See Linked clones.

Storage usage looks larger than expected

APFS clones and snapshots share blocks, so physical sizes over-count. Private size is what deleting the VM would free.

A VM whose linked clones were all deleted can keep disk layers nothing reads. Its Overview shows how much, with Flatten Disk to merge them.

A backup failed, or didn't run

VM Settings → Backup and the Overview say why the last backup failed. MacVisor tries again an hour later, then less often. See Backups.

• The folder isn't there: connect its drive or mount its share. After three days, Tasks says so.
• A running VM on a drive that isn't APFS is backed up only while it's stopped. Shut it down and click Back Up Now, or move it to an APFS drive.
• A copy failed its check: the backup drive returned something other than what was written. Nothing that looks complete is left behind; check the drive.
• "Busy": another task held the VM, or another VM was being backed up to the same drive. A scheduled backup waits its turn.

Converting a disk to ASIF is refused

• The VM must be stopped, with no suspended session and no linked-clone disk.
• Conversion needs free space equal to the disk's full size. MacVisor says how much.

macOS has run out of resources for attaching disk images

After many disk image operations, macOS can refuse to attach more until it restarts. Nothing is damaged. Restart the Mac and try again.

Licensing

License activation fails, or mvz says MacVisor isn't licensed

If you bought a license during the trial, enter the key under Settings → License → Upgrade from the Trial. It replaces the trial.

See Activate your license.

Sending us a problem report

1. Choose Help → Report a Problem… (also in the Logs menu). MacVisor saves a zip of:

   • the app, service and runner logs, and a summary of its state;
   • MacVisor's crash reports from the last 14 days, and those of the Virtualization process that ran MacVisor's own VMs (com.apple.Virtualization.VirtualMachine): its crash, hang, spin and CPU resource reports. Reports of other apps' VMs, such as UTM's, are left out;
   • the last 256 KB of each VM's serial console log written in the last 14 days, as console-logs/<short id>.console.log.

   What doesn't fit the size budget, or is left out, is listed in a skipped.txt.

2. Click Email to Support to open a message to support@scaleninja.com with the report attached, or Show in Finder to send it your own way.

Nothing is uploaded automatically. Help → Email Support… starts a message with your MacVisor and macOS versions filled in.

On a Mac you reach only over SSH

Report a Problem is in the app only. Over SSH, collect the same files yourself, as the account that runs MacVisor. They are:

The app's and the service's logs start again at 8 MiB, and keep the previous one beside them with .1 added to its name. The helper's log does the same at 512 KiB. Each VM's runner log starts again each time its runner starts, and keeps the last five runs' logs beside it, .1 (the run before) to .5. These commands put everything, with the versions and the state of the service, the license and the VMs, in one zip in your home folder:

out=~/macvisor-report-$(date +%Y%m%d-%H%M)
mkdir -p "$out"
mvz version > "$out/version.txt" 2>&1; sw_vers >> "$out/version.txt"
mvz service status > "$out/service.txt" 2>&1
mvz license status --verbose > "$out/license.txt" 2>&1
mvz list --json > "$out/vms.json" 2>&1
mvz tasks --json > "$out/tasks.json" 2>&1
cp -R ~/Library/Application\ Support/MacVisor/logs ~/Library/Application\ Support/MacVisor/operations "$out/" 2>/dev/null
cp /var/log/macvisor-adminhelper.log{,.1} "$out/" 2>/dev/null
find ~/Library/Logs/DiagnosticReports /Library/Logs/DiagnosticReports \( -iname 'MacVisor*' -o -iname 'com.apple.Virtualization.VirtualMachine*' \) -mtime -14 -exec cp {} "$out/" \; 2>/dev/null
ditto -c -k --keepParent "$out" "$out.zip" && echo "$out.zip"

Copy the zip to your own Mac, for example with scp host:macvisor-report-*.zip ., and attach it to an email to support@scaleninja.com. Like the app's report, it holds your VMs' names, settings and paths, and the helper's log covers every account on the Mac. The Virtualization process's reports this copies may include other apps' VMs. Read it before you send it.

For a guest that didn't set itself up, add its own log: /var/log/macvisor-setup.log in a Linux VM (mvz exec <vm> -- sudo cat /var/log/macvisor-setup.log), or C:\ProgramData\MacVisor\setup-complete.log in Windows.

Community, issues and feature requests

Ask other MacVisor users and share what you've built on r/macvisor, or in the #macvisor channel of the MacAdmins Slack. Report a bug or ask for a feature in public at github.com/macvisor/macvisor/issues. Both are also in MacVisor's Help menu. Don't attach a problem report to a public issue: it holds your VMs' names, settings and paths. Email it to support@scaleninja.com instead.

What to include, and when we answer

Say what you did, what you expected and what happened instead, with the exact message, and attach the report. Name the VM involved and its guest system. For a license or trial question, include the Mac's Support ID: it's in Settings → License (with a Copy button) and mvz license status, and Help → Email Support… puts it in the message for you. It's a one-way hash, not your Mac's serial number.

Every license, and the trial, comes with email support. Enterprise adds 8x5 business support, or 24x7 support with the response times of its agreement. See Compare licenses.