MacVisor Beta

Troubleshooting

Service, permission, download, installation, guest tools, shell, network, storage, snapshot, licensing, and CLI problems, and what to do about each.

The library or CLI cannot reach the service

mvz service status

Every mvz command exits with status 4 when the service can't be reached at all, and 5 when it is there but doesn't answer in time, usually because it is busy (3 is "no such VM", 1 a failed operation). After a 5 the service may still be doing what you asked; mvz tasks shows it.

If nothing answers, open MacVisor. It re-registers a background item that is installed but not answering, and when only you can fix it (macOS lets no app approve its own background item) it shows a sheet saying what to do and opens System Settings → General → Login Items & Extensions once: switch MacVisor on under Allow in the Background, or, if the sheet says "macOS needs a nudge", off and then on again. It does this at launch and whenever the service stops later, and closes the sheet by itself once the service answers. The usual cause is a differently signed copy of MacVisor installed over this one (a development build, then a notarised release), which macOS won't start until it is approved again; updates from one release to the next don't do this.

Otherwise restart it from the dashboard's Control Service panel, Assistant → Restart Background Service, or mvz service restart. The dashboard's button and mvz service restart let work in progress, such as a clone or an export, finish first and say so. The Logs menu shows the service, app, and per-VM runner logs; mvz service logs --tail 200 shows the service's. Each VM's runner log is ~/Library/Application Support/MacVisor/logs/<VM id>-runner.log.

If the service answers but the library doesn't load when MacVisor opens, for example while an external disk spins up, the sidebar says Couldn't load your library, with the reason and Retry. MacVisor also keeps trying by itself, backing off to once a minute.

MacVisor says the background service is still starting

Right after the Mac starts up, the background service can take a minute to start. Until it answers, MacVisor says "MacVisor's background service is still starting…" instead of showing errors, and the Setup Assistant shows the service as Starting…. MacVisor doesn't restart a service that is only slow; one that stays silent for two minutes is restarted once. If it still doesn't answer after that, see above.

mvz says the service is still running an older MacVisor

Until it restarts, the background service keeps running the build it started with. A newer mvz then reports that MacVisorService is still running an earlier MacVisor build, which doesn't understand the request, and mvz service status shows the service's build and says when it differs from the CLI's. Open MacVisor, which restarts the service, 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.

A VM is busy, or still open in another runner

  • "dev" is busy: exporting. While a VM is exporting, moving, suspending, taking or restoring a snapshot, or converting or flattening a disk, other actions on it are refused after a few seconds instead of waiting in line. Shorter work makes them wait only as long as the app or mvz waits for an answer, so nothing starts after you were told it timed out. Try again when the task pane or mvz tasks shows the work has finished. Power Off doesn't wait behind a snapshot or a suspend.
  • "dev" is still open in another MacVisor VM Runner. A runner from an earlier start still has the VM's disks open, for example one that came up late after a start timed out. MacVisor never starts a second runner on the same disks. Wait a moment and start again, or power the VM off (mvz poweroff dev), which ends that runner.

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

A VM that can't start says why in one message, with the path of its runner log for the details; Logs → Runner Logs opens the same log. A VM that stops with an error gets a task in the task pane and mvz tasks saying why in plain words, for example that the drive holding it became unavailable, or that the Mac ran out of disk space. Reconnect the drive or free some space, then start the VM again.

A storage location says it is waiting for permission

macOS blocks a background service's read of a removable, network, or protected folder until you consent.

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

mvz service status lists each such location as Waiting for permission: <path> (pendingStorageRoots with --json). Until allowed, the location shows as waiting, not empty.

A download stalled, failed, or was cancelled

Downloads are tasks, with size, speed, and time left in the task pane and mvz tasks. They resume: the partial file stays in the storage location as Templates/Downloads/<file>.partial (Templates/Installers/Downloads for a macOS installer), and the next mvz images pull or mvz create of the same image carries on, whether it stopped because of an interruption, a mvz tasks cancel, or a MacVisor restart. A download cut off by a restart of the background service picks up again by itself; one you cancelled stays stopped until you pull or create that image again. An abandoned partial is removed after two weeks; delete it by hand sooner if you want the space.

A download that won't fit in the storage location's free space is refused before it starts, with how much to free. One that fills the volume anyway stops and keeps what it got; free some space and pull again, and it carries on from there.

A file that fails its checksum is discarded and the task says so; pull again. For the "latest" entries (Ubuntu, Debian, Rocky Linux, AlmaLinux, CentOS Stream, openSUSE Leap) the checksum list comes from the vendor at download time, so a vendor outage fails verification, not the download.

Installation media will not boot

  • macOS guests need a compatible IPSW on Apple Silicon. A local .ipsw is checked when you add it and refused there if it is not a restore image for virtual Macs.
  • Linux media must be ARM64, including cloud images you add with mvz images add.
  • Keep the ISO attached during installation and eject it afterwards (mvz set <vm> --iso none).
  • Check free space in the storage location.

A suspended VM won't resume

The usual cause is a locked screen. macOS restores a saved session only while you are logged in at the Mac with the screen unlocked; saving works while locked, but a restore attempted then fails with a bare "permission denied". MacVisor checks before trying. Over SSH, mvz resume says "This Mac's screen is locked…" and that the saved session is intact; the Overview says Waiting for the Mac to be unlocked. Unlock the Mac (or use Screen Sharing) and resume again. A suspended VM set to start at login waits and resumes after you unlock.

Otherwise the VM's Overview says why the session did not restore and offers Try Again and Start from Disk…; mvz show <vm> says the same. The most common reason is an update: of macOS, or during the beta of MacVisor ("MacVisor was updated since this VM was suspended…"). Such a session can't be restored on the new version, so only Start from Disk… is offered. 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 are not the cause: the session resumes with the settings it was saved with, and yours apply after the next shutdown. If the session needs something that is gone, such as a custom network deleted since, MacVisor says that changing settings won't help and suggests starting from disk.

On macOS 27, VMs whose disk caching is Cached have sometimes failed to resume. If you rely on Suspend or live snapshots, set Caching to Automatic in VM Settings → Storage.

mvz start <vm> --recovery is refused for a suspended VM: resume it and shut it down, or discard the saved session, first.

Suspend is refused or fails

Suspending writes the VM's memory to its volume. MacVisor refuses up front when the volume clearly lacks the space, and says how much is needed. A save that still runs out of space fails without harming the guest: the VM keeps running. Free some space and suspend again, or shut the VM down.

Guest tools stay disconnected

  1. Guest Tools must be on in VM Settings → Sharing, and the Guest Agent Channel (vsock) device present under Advanced.
  2. A Linux cloud-image VM gets the agent from cloud-init on first boot; mvz wait <vm> returns when that is done. A VM created with --no-agent has none.
  3. A macOS 27 guest with automatic setup and Remote Login gets the agent from MacVisor after first boot, over SSH with the account's password. If the password changed, Remote Login was turned off, or the runner lacks Local Network permission, install by hand.
  4. In a macOS guest, the agent must be dragged into Applications and opened from there; opened from the mounted volume it shows copy instructions and quits, because the volume is rebuilt each boot.
  5. Turn MacVisor Agent on in the guest's Login Items & Extensions if macOS is holding it for approval. If the agent is on there but only runs once you open it by hand, the copy in Applications is signed differently from the one that registered the login item, and macOS stops it at login. Copy the agent from the current MacVisor Agent volume into Applications and open it once; it registers itself again.
  6. In a Linux guest installed from an ISO, re-run sudo mount -o ro -L MACVISOR_AGENT /mnt && sudo sh /mnt/install-linux.sh and check the macvisor-agent service (systemd or OpenRC).

Only one agent can hold its ports; a second copy quits rival copies at launch and reports a bind failure. The agent does not need ordinary guest network access. In a macOS guest it restarts itself after a crash.

mvz shell asks for a password or is refused

  • Linux: shell uses your SSH keys, and MacVisor's own key, which a VM made on a Mac without any key of yours authorises instead. The guest account has no password, so Permission denied (publickey) means none of them is authorised there: a VM created with --no-ssh-keys, or before the key you now use existed, has nothing to match. Add the key to the guest's ~/.ssh/authorized_keys, or recreate with --ssh-key. Plain ssh and editors don't offer MacVisor's key; for them, make one of your own (ssh-keygen -t ed25519) and authorise it.
  • macOS: Remote Login must be on. Create the VM with --ssh, or turn it on in the guest's Sharing settings. The first connection asks for the account's password once and authorises your key; a macOS 27 guest with automatic setup has that done already. The default account is mac / macvisor; --user <name> signs in as another.
  • A VM whose cloud-init has not finished still accepts a shell; --wait holds until setup is done.

No route to host

The VM runs and has an address, yet a connection to that address fails with No route to host and nothing is logged. Since macOS 15 each app needs permission to talk to the local network, and VMs live on one (192.168.64.x by default). Which app's permission counts depends on who connects:

  • mvz shell and mvz exec, ssh <vm>.mvz after mvz ssh-config --install, Docker contexts and port forwards don't use the VM's network: they go through the VM runner to the guest agent over vsock. Only when the agent isn't answering do shell and exec connect over the network instead, from your terminal app.
  • Anything run in a terminal that connects to the guest's address, such as curl http://dev.mvz:8080, plain ssh to the VM's IP, or that fallback, uses the terminal app's own Local Network permission (Terminal, iTerm, or whichever app runs the command). Turn it on under System Settings → Privacy & Security → Local Network.
  • MacVisor's own connections, such as the automatic account and agent setup in macOS 27 guests, need the permission for the app and the VM runner, both listed as MacVisor. Open Assistant → Setup Assistant…: its Local Network item shows which is missing, with a button to ask again and one to open Local Network settings. See Local Network.

If the permissions are on, look for something that captures or blocks the VMs' range: a VPN that sends all traffic, or 192.168.64.0/24, through its tunnel or blocks local network access, a content filter or firewall app, or a firewall on the VM's MacVisor network that denies inbound traffic. Disconnect the VPN or allow local network access in its settings, let the traffic through, and try again.

The VM has no network

NAT: check the host is online. Bridged: the chosen interface must exist and the LAN must admit new devices. Custom network: the VM's NIC must point at a network this Mac has. A VM that arrived with an unknown network was put on the Default MacVisor Network, and the service log says so.

A host-only network with a fixed subnet gets no DHCP from macOS; configure addresses in those guests yourself. A shared network cannot have a fixed subnet on macOS 27. See Custom networks.

Port forwarding does not connect

Guest tools must be connected, the guest service must listen on the port, and the host port must be free. Check mvz ports list <vm>, and mvz show <vm>, which lists the automatic forwards and why one isn't active, for example "the port is already in use on this Mac". Forwards reach the guest service through its loopback, so services bound to 127.0.0.1, ::1, 0.0.0.0 or :: are covered; one bound to a single specific guest address isn't, so bind it to loopback or to all addresses. Some ports are never forwarded automatically, or held back with a reason; see What automatic forwarding leaves out and forward those by hand. A per-VM forward of UDP needs --udp.

http://<vm>.mvz:<port> is different: it goes to the guest's own address, not through a forward, so it needs the service bound to 0.0.0.0 (or the guest's address), and the guest's firewall must let it in.

Network-level forwards on a custom network need no guest tools but are fixed while any VM uses the network: stop those VMs, edit, start again.

A DHCP reservation is not honoured

Reservations hold only where macOS serves DHCP (shared networks, and host-only networks on an automatic subnet), and on a shared network only while vmnet keeps the subnet, which it re-picks whenever the network is recreated. The guest must identify itself by MAC in its DHCP request; cloud-image VMs do, a hand-installed Ubuntu does not until dhcp-identifier: mac is set. See Custom networks.

Firewall rules do not take effect

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

  • "Starts when a VM runs on this network." The network has no subnet yet. The rules load when its first VM starts.
  • "Needs approval to enforce." Click Approve…, or turn MacVisor's network helper on under System Settings → Login Items & Extensions.
  • "MacVisor's network helper didn't answer." If MacVisor is already switched on under Allow in the Background in System Settings → General → Login Items & Extensions, switch it off and then on again: after a differently signed build of MacVisor (a development build, then a release) macOS can keep refusing to start the helper until then. MacVisor notices, says so, and opens Login Items; the firewall is applied again once the helper starts.
  • "Not enforced." The reason is shown under the rules. A subnet outside 192.168.0.0/16, outside /20 to /30, or overlapping one of the Mac's own networks can't carry rules. On a standard account, the helper takes firewall changes only while that account is the one at the Mac's screen.
  • A rule is skipped, or mvz networks firewall refuses every change. A rule that can't be enforced as written is marked in the editor and skipped while the others apply. Until it is fixed in the app, or dropped with --clear, the CLI refuses changes to that network and names the rule.
  • Traffic between two VMs still flows. That is expected: VM-to-VM traffic on one network is switched inside vmnet and never reaches the packet filter. Use separate networks.
  • A VM still has IPv6. VMs that were running when the firewall went on keep IPv6 until every VM on the network has stopped. A shared network with NAT44 off keeps IPv6 by design, unfiltered; the firewall is IPv4 only.
  • Nothing matches. sudo pfctl -a 'com.apple/900.macvisor.firewall' -sr reads back the rules pf holds.

mvz is not found in Terminal

The /usr/local/bin/mvz and macvisor links are made by the network helper at first-run setup. Without it, run the binary from the bundle:

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

MacVisor creates the links as soon as the helper is approved, while the app is open. The Setup Assistant's Command-Line Tool item does it on demand.

A macOS install is in the way, or was interrupted

While macOS is being installed into a VM, MacVisor refuses to start, change, clone, export, snapshot, or delete it, and says "macOS is still being installed on …". Wait for the install, or stop it with Cancel Task in the task pane (mvz tasks cancel <task-id>). Restarting the background service doesn't stop an install.

An install you cancel, or one that ends early because the Mac logged out or restarted or the disk filled up, is marked cancelled or failed in the task pane, with the reason, and the VM is left stopped. Use Erase and Install macOS… to try again, or delete the VM.

Creating or deleting a VLAN interface asks for a password

The network helper makes VLAN changes without asking only for an administrator account, and deletes only VLAN interfaces MacVisor's helper created. A standard account, a Mac where the helper isn't installed, or deleting a VLAN interface made in System Settings, without the helper, or by an earlier MacVisor, gets the macOS administrator password prompt each time. See VLAN interfaces.

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. MacVisor says how much.

macOS has run out of resources for attaching disk images

After many disk image operations, macOS can refuse to attach any more disk images until the Mac restarts. MacVisor then says "macOS has run out of resources for attaching disk images. Restart your Mac, then try again." The template, clone, or disk that failed isn't damaged: restart the Mac and do it again.

VMs did not come back after a reboot

Check the dashboard's Unattended Auto-Start panel: the background service must be enabled, automatic login on, sudo pmset autorestart 1 set for power cuts, and FileVault off or someone present to unlock. See Always-on host.

Each auto-start is listed in the task pane and mvz tasks, with what happened and the reason when it failed. VMs that were shut down at logout, the default in Settings → General → Logout and Shutdown, boot fresh rather than resuming where they were; choose Suspend VMs there to have them resume.

When a suspended VM's session doesn't restore at login, MacVisor keeps it while the Mac is locked or the VM's storage isn't mounted yet, and resumes it once that changes. A session that provably can't restore goes to the Trash and the VM starts from its disk; any other failure is retried once, and if the restore fails again, the same happens. A session kept because the retry failed before the session was read stays suspended: resume it again, or use Start from Disk…. See Always-on host.

A live snapshot cannot resume

Live memory restores only on the virtual hardware it was saved with. A revert puts the snapshot's settings back along with its disks, so CPU, memory, disk, NIC, display, or device changes made since are undone rather than in the way; the revert sheet says so. After a macOS update on the Mac, or during the beta a MacVisor update, expect the VM to boot from the snapshot's disk instead. A locked screen is a different case; see above.

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

It is part of a linked-clone chain, or reads through a cloud-image template. A VM others were forked from cannot be deleted or reverted until those clones are gone; a clone forked from a VM cannot be exported, templated, or full-cloned, because part of its disk lives in its source. A VM made from a template (every cloud-image VM) can be templated and full-cloned, but not exported. MacVisor names the VMs involved. mvz flatten <vm> (stopped, no snapshots) makes a disk self-contained. See Linked clones.

A suspended VM can't be made a template either, because its disk was never written out: resume it and shut it down, or discard its saved state, first.

Storage usage looks larger than expected

Logical size, physical allocation, and private size answer different questions; APFS snapshots and clones share blocks, so physical sizes over-count. Private size is what deleting would reclaim.

A VM whose linked clones have all been deleted may keep disk layers nothing reads; its Overview says how much space they hold, with Flatten Disk to merge them (stopped, with no snapshots). Deleting the last clone hands the layer back by itself, if the VM hasn't run since the fork and has no snapshots taken while it was forked.

An external VM location disappeared

The location shows Offline in the sidebar's Storage section. 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 produces duplicate identities.

Storage locations can't be added or changed

MacVisor keeps the list of storage locations in ~/Library/Application Support/MacVisor/locations.json. If that file is damaged, or was written by a newer MacVisor, MacVisor never overwrites it: it uses the locations it can still read from it and refuses to add, remove, or change locations, saying why. Each change keeps the version it replaces beside it as locations.json.bak. Put that back, or fix the file, then try again.

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

  • The key is refused. Copy the whole key without extra spaces; it begins with MVZ-. A key for another product is refused.
  • The key is active on another Mac. A MacVisor 27 license covers one Mac (every account on it), and each Enterprise key 10. Deactivate on This Mac… on the other Mac, or click Move to This Mac here (mvz license activate <key> --move). Moves from the new Mac are limited to 3 in 30 days; deactivating on the old Mac first never counts. See Moving a license to another Mac.
  • Another account on this Mac asks for a key. With the Network Helper on, one license covers every account on the Mac automatically. Without it, enter the same key in that account's Settings → License; it doesn't use a second Mac. See Licenses on a Mac with several accounts.
  • The trial won't start again. There is one trial per Mac; reinstalling, another account, or another email doesn't start a new one. If the beta held a free trial key, or a key the licensing server doesn't recognise, MacVisor started the Mac's trial by itself the first time the updated MacVisor reached the licensing server, so its days count from then. If the Mac's trial was used by someone else (a second-hand or shared Mac), contact support: we can reset it. If too many trials were started from your network today, try again tomorrow or ask support to raise the limit.
  • The Mac is offline. Starting the trial, activation, and the weekly re-check need ScaleNinja's licensing server (keys.scaleninja.com, port 443). MacVisor makes the re-check whether or not the app is open; after a check that got no answer it tries again after 5 minutes, then at growing intervals up to every 6 hours. After 30 days since the last successful check, the badge reads License needs verification (the License tab says Needs checking), and new VMs, cloud images, and other licensed actions pause until Settings → License → Refresh License (or mvz license refresh) succeeds; existing VMs keep running.
  • The badge says Confirming license. MacVisor couldn't verify its licensing record on this Mac (it was copied from another Mac, or edited), so it is confirming the license with the licensing server. Connect the Mac: it tries again by itself after 5 minutes, then at growing intervals up to every 6 hours, and when you try to add a VM (at most every 30 seconds); or click Refresh License / run mvz license refresh. Nothing needs re-entering.
  • The badge says Activate again. The licensing record on this Mac couldn't be read at all. Enter your key again in Settings → License or with mvz license activate.
  • mvz license activate says to give the key or -. It asks for the key only in an interactive terminal. Over SSH use ssh -t, or pipe the key in: echo "$KEY" | mvz license activate -.
  • The badge says Reinstall MacVisor. This copy of MacVisor is damaged or was changed. Activation is off in that state, because it can't license a damaged copy. Click the badge, or Download MacVisor… in Settings → License, and reinstall from scaleninja.com/macvisor; a key already activated on this Mac works again afterwards. Your VMs are untouched.
  • The License tab says Deactivating. The Mac couldn't reach the licensing server when you deactivated it. MacVisor releases the activation the next time it can; until then adding VMs is paused, unless you activate a key again.
  • You bought a license during the trial. Enter the new key in Settings → License, under Upgrade from the Trial, or in the key field of the prompt shown at launch. It replaces the trial; there is no need to end it first.
  • mvz create, clone, import, images pull, or images add, the New VM form, or getting a macOS installer says MacVisor isn't licensed. Start the trial with mvz license trial, or activate a key with mvz license activate or in the app under Settings → License. The New VM form keeps Create disabled until then and links to the License settings. Every other command works unlicensed.
  • The License tab says the background service hasn't reported the license. The app reads the license through the service, so it can't show it while the service isn't answering. See The library or CLI cannot reach the service.

See Activate your license.

Sending us a problem report

Logs → Report a Problem… zips the app, service, and runner logs with a summary of this Mac's MacVisor state, saved where you choose. Attach it to your email; nothing is uploaded on its own.