Skip the cutscene

Errors

SYSTEM NOTICE: The System couldn't be bothered to narrate this page. Enjoy the boring version, Crawler. The facts are the same either way.

When a command fails, Pomme prints what happened, the next step when there is one, and a stable error code with a link to its entry on this page:

Error: No Pomme-owned VM named my-vm exists. Create it with `pomme create my-vm` or run `pomme list`.
Error code: vm-not-found. For help, see https://pommevm.dev/reference/errors/#vm-not-found

With --format json or --format jsonl, the failed result has the same code in its errorCode field, the next step in hint, and the underlying reasons in causes. For details, see Structured output. Codes don’t change meaning between releases, so scripts can match on them.

If an error doesn’t explain itself, run pomme bug-report to collect the details that a maintainer needs into one file.

The config file isn’t valid.

Cause: The file named in the message has a syntax error, an unknown key, or a value of the wrong type.

Resolution:

  1. Correct the key that the message names.
  2. See Config file for the accepted keys.

A required credential isn’t available.

Cause: The operation needs the guest owner’s credential, and Pomme couldn’t find it in the Keychain, the environment, or a prompt.

Resolution:

  1. Run the command in an interactive terminal so that Pomme can prompt for it.
  2. See Change SIP and AMFI.

Pomme couldn’t read structured data.

Cause: A JSON document, such as a reply from the VM helper or a file in a VM bundle, has a missing key or a value of the wrong type.

Resolution:

  1. If the data came from a file that you edited, restore it.
  2. Otherwise, run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

A file operation failed.

Cause: Pomme couldn’t read or write a file. The message gives the reason.

Resolution: Check the path and the reason in the message.

A file doesn’t exist.

Cause: A file or directory that the operation needs is missing.

Resolution: Check the path in the message.

A host operation failed.

Cause: An operation on this Mac, such as a file copy or a tool that Pomme runs, failed. The message gives the reason.

Resolution:

  1. Read the reason in the message and correct it.
  2. If the reason isn’t clear, run pomme bug-report and attach the file to a new issue.

The disk is out of space.

Cause: The volume that holds your VMs, or the volume that Pomme was writing to, has no free space.

Resolution:

  1. Free space on the volume. Each macOS VM needs as much free space as its disk size, which is at least 40 GB.
  2. Run pomme list and delete VMs that you no longer need with pomme delete NAME.

There isn’t enough free space to create the VM.

Cause: Before it downloads or writes anything, pomme create and pomme template create compare the free space on each volume they use with what the creation needs: the rest of the restore image download, about 35 GB for an installed macOS system (or the disk size, if it’s smaller), and, for a VM cloned from a template, about 5 GB for the clone’s own changes. The message lists each part.

Resolution:

  1. Free at least the amount that the hint names on that volume.
  2. Run pomme list and delete VMs that you no longer need with pomme delete NAME.
  3. Run pomme create --dry-run to see the space check without creating anything.

A host file can’t be used.

Cause: The host path that you gave is missing, is a directory or a symbolic link, or isn’t readable.

Resolution: Give the path of a regular, readable file.

This Mac can’t run Pomme VMs.

Cause: Virtualization.framework isn’t available. Pomme needs a Mac with Apple silicon.

Resolution: Run Pomme on a Mac with Apple silicon. See Requirements.

This Mac needs a software update.

Cause: The restore image needs newer system software on this Mac than it has.

Resolution: Install the available updates in System Settings > General > Software Update, then retry.

Pomme hit an unexpected error.

Cause: An error reached the command without a description. This is a bug in Pomme.

Resolution: Run pomme bug-report and attach the file it writes to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The arguments aren’t valid.

Cause: The command line doesn’t match the command’s usage.

Resolution: Run pomme help COMMAND to see the usage.

A value in the request isn’t valid.

Cause: An argument, flag value, or path doesn’t meet the command’s rules. The message names the value and the rule.

Resolution:

  1. Correct the value that the message names.
  2. Run the command with --help to see the accepted values.

A Keychain operation failed.

Cause: Pomme stores VM credentials in your login Keychain. macOS refused the request; the message gives the Keychain’s reason.

Resolution:

  1. Unlock your login Keychain, then retry.
  2. If macOS asks whether pomme can access an item, allow it.

A network request failed.

Cause: Pomme couldn’t reach a server, such as Apple’s restore image catalog.

Resolution: Check the network connection, then retry.

The operation was cancelled.

Cause: You pressed Control-C, or another process cancelled the operation.

Resolution: Run the command again if you didn’t mean to cancel it.

The operation failed.

Cause: An operation reported a failure without a more specific code.

Resolution:

  1. Read the message for the reason.
  2. If the reason isn’t clear, run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Permission was denied.

Cause: macOS refused access to a file, directory, or resource.

Resolution:

  1. Check the ownership and permissions of the path in the message.
  2. Run Pomme as the user who created the VM, not with sudo.

The security configuration isn’t valid.

Cause: A security setting or its combination with other flags isn’t supported.

Resolution: Correct the setting that the message names.

A system call failed.

Cause: A low-level operation, such as opening a socket or a file, failed. The message names the call and the reason that macOS gave.

Resolution:

  1. Read the reason in the message.
  2. If it doesn’t explain the failure, run pomme bug-report and attach the file to a new issue.

A macOS framework reported an error.

Cause: A system framework failed. The message gives its reason, and the error’s causes give its domain and number.

Resolution:

  1. Read the reason in the message.
  2. If it doesn’t explain the failure, run pomme bug-report and attach the file to a new issue.

The command needs an interactive terminal.

Cause: The command prompts or draws a full-screen interface, and standard input or output isn’t a terminal.

Resolution: Run the command in Terminal, or use the non-interactive form that its --help describes.

The operation timed out.

Cause: The operation didn’t finish within its time limit.

Resolution:

  1. Retry with a larger --timeout value.
  2. Run pomme status NAME to check that the VM is responsive.

The boot firmware repair didn’t complete.

Cause: After it wrote the VM’s auxiliary storage, Pomme read the file back and didn’t find the firmware it wrote. The message names the backup of the original file.

Resolution:

  1. With the VM stopped, copy the backup that the message names over the AuxiliaryStorage file in the VM bundle.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme doesn’t recognize the VM’s boot firmware.

Cause: pomme firmware repair changes the VM’s auxiliary storage only when its firmware slots match the layout that Pomme has seen macOS write. This VM’s file doesn’t, so Pomme changed nothing.

Resolution:

  1. Run pomme firmware inspect NAME to see what Pomme found.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The snapshot doesn’t exist.

Cause: The VM has no snapshot with the name that you gave.

Resolution: Run pomme snapshot list NAME to see the VM’s snapshots.

Virtualization.framework reported an error.

Cause: The framework that runs the VM failed. The error’s causes give its VZErrorDomain code.

Resolution:

  1. Retry the operation.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

This Mac doesn’t support the virtualization feature.

Cause: The operation needs a Virtualization.framework feature that this Mac or macOS version doesn’t have.

Resolution: Update macOS on this Mac, or run the operation on a Mac that supports it.

The VM bundle is damaged.

Cause: A file in the VM bundle, such as its hardware model or machine identifier, is missing or invalid.

Resolution: Restore the VM from a backup or a snapshot, or create it again.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM’s configuration isn’t valid.

Cause: Virtualization.framework rejected the VM’s configuration on this Mac.

Resolution:

  1. Run pomme inspect NAME to check its CPU, memory, and disk settings.
  2. Lower the VM’s memory if it exceeds what this Mac supports.

Pomme refused to delete the VM.

Cause: Pomme deletes only a verified Pomme-owned VM, and only when the confirmation matches its name.

Resolution: Check the name with pomme list, then retry pomme delete NAME.

The VM’s disk image can’t be used.

Cause: Virtualization.framework couldn’t open the VM’s disk image. It might be damaged or in use by another process.

Resolution:

  1. Make sure that no other process has the VM open.
  2. Restore the VM from a snapshot, or create it again.

This Mac can’t run the VM’s hardware model.

Cause: The VM was created for a hardware model that this Mac doesn’t support, usually because it was created on a newer Mac.

Resolution: Run the VM on the Mac that created it, or create a new VM on this Mac.

Too many macOS VMs are running.

Cause: macOS limits how many macOS VMs can run at the same time on one Mac.

Resolution:

  1. Stop another VM with pomme stop NAME, then retry.
  2. Run pomme list to see which VMs are running.

The memory size is out of range.

Cause: The requested memory is below the guest’s minimum or outside the range that this Mac supports.

Resolution: Pass a --memory value within the range that the message gives, such as --memory 4GB.

The VM doesn’t exist.

Cause: No Pomme VM has the name that you gave.

Resolution:

  1. Run pomme list to see your VMs.
  2. Create the VM with pomme create NAME.

The VM isn’t running.

Cause: The command needs a running VM, and the VM’s helper isn’t running.

Resolution: Start the VM with pomme start NAME.

No VM was named.

Cause: The command needs a VM name, and none was given or set in POMME_VM_NAME.

Resolution: Pass the VM name, or set POMME_VM_NAME.

The VM is paused in the other boot mode.

Cause: pomme start resumes a paused VM only in the boot mode that it was paused in.

Resolution:

  1. Stop the VM with pomme stop NAME, then start it in the boot mode that you want.
  2. To continue in the same mode, run pomme start without changing the boot mode.

The VM is running.

Cause: The command needs a stopped VM.

Resolution: Stop the VM with pomme stop NAME, then retry.

The VM is running in the other boot mode.

Cause: pomme start asked for normal or Recovery boot, and the VM is already running in the other one.

Resolution: Stop the VM with pomme stop NAME, then start it in the boot mode that you want.

Saving or restoring the VM’s state failed.

Cause: Virtualization.framework couldn’t save or restore the VM’s memory state.

Resolution: Stop the VM with pomme stop NAME, then start it again.

The VM couldn’t start.

Cause: Virtualization.framework failed to start the VM. The message gives its reason.

Resolution:

  1. Read the reason in the message.
  2. Check the helper log in the VM bundle, or run pomme bug-report NAME.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM’s state doesn’t allow this operation.

Cause: The operation needs the VM in a different state, such as stopped, running, or paused. The message names the state that it needs.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Change it with pomme start, pomme stop, pomme pause, or pomme resume, then retry.

The macOS installation failed.

Cause: Virtualization.framework couldn’t install macOS from the restore image into the VM.

Resolution:

  1. Check that the volume has enough free space for the VM’s disk.
  2. Download the restore image again, then run pomme create NAME --resume.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The restore image catalog couldn’t be loaded.

Cause: Apple’s restore image catalog returned an error status.

Resolution: Check the network connection, then retry.

The restore image download failed.

Cause: Apple’s server returned an error status for the download.

Resolution: Check the network connection, then retry the download.

The restore image can’t be used.

Cause: Virtualization.framework couldn’t load the restore image or its catalog.

Resolution: Download the image again with pomme ipsw download, then retry.

The restore image isn’t downloaded.

Cause: The selected restore image is remote, and the command needs a local copy.

Resolution: Download it with pomme ipsw download, or pass a local file with --restore-image.

The device identifier isn’t known.

Cause: The restore image catalog has no entry for the device identifier that you gave.

Resolution: Run pomme ipsw list to see the available images.

The restore image doesn’t support this Mac.

Cause: The restore image has no configuration that this Mac can run.

Resolution: Choose a newer restore image with pomme ipsw list.

The VM helper couldn’t run the command.

Cause: The running VM’s helper reported a failure without a more specific code. The message gives its reason.

Resolution:

  1. Read the reason in the message.
  2. Run pomme bug-report NAME and attach the file to a new issue if the reason isn’t clear.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t verify the VM helper.

Cause: Pomme stops a helper only after it confirms that the process is the helper it started.

Resolution: Run pomme status NAME. If the VM is stuck, quit its helper process in Activity Monitor.

The VM helper doesn’t match this version of Pomme.

Cause: The running VM’s helper started from a different version of Pomme and speaks another control protocol version or lacks a feature.

Resolution: Restart the VM with pomme stop NAME and pomme start NAME.

The VM helper sent an invalid reply.

Cause: A reply from the running VM’s helper was malformed or incomplete.

Resolution:

  1. Restart the VM with pomme stop NAME and pomme start NAME.
  2. Run pomme bug-report NAME and attach the file to a new issue if it happens again.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The control socket path is too long.

Cause: macOS limits Unix socket paths to 104 bytes, and the VM bundle’s path is longer.

Resolution: Move the VMs to a shorter path, or use a shorter VM name.

The VM helper exited while it started.

Cause: Each running VM has a helper process. It exited before it opened its control socket, usually because the VM couldn’t start.

Resolution:

  1. Read pomme-helper.log in the VM bundle; the message gives its path.
  2. Run pomme bug-report NAME and attach the file to a new issue if the log doesn’t explain the failure.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM helper didn’t start in time.

Cause: The helper process didn’t open its control socket before the time limit.

Resolution:

  1. Retry with a larger --timeout value.
  2. Read pomme-helper.log in the VM bundle; the message gives its path.

The VM helper didn’t respond in time.

Cause: A request to the running VM’s helper didn’t finish within its time limit.

Resolution:

  1. Retry with a larger --timeout value.
  2. Run pomme status NAME to check that the helper is responsive.

The VM helper doesn’t know the command.

Cause: The VM helper is older or newer than this pomme and doesn’t support the command.

Resolution: Restart the VM with pomme stop NAME and pomme start NAME so that its helper matches this pomme.

The guest agent is still connecting.

Cause: PommeAgent is authenticating with the host.

Resolution: Retry in a moment.

The guest agent disconnected.

Cause: The connection to PommeAgent closed before it replied, often because the guest restarted, shut down, or went to sleep.

Resolution: Run pomme status NAME, then retry when the agent is connected.

The guest agent couldn’t start.

Cause: PommeAgent rejected its launch arguments, couldn’t verify its own code or credential, or couldn’t open its connection to the host.

Resolution:

  1. Run pomme agent status NAME to check the agent.
  2. Run pomme agent repair NAME to reinstall it.

The guest agent sent an invalid reply.

Cause: A message from PommeAgent didn’t follow the agent protocol, often because the agent and pomme versions differ.

Resolution:

  1. Update the agent with pomme agent update NAME.
  2. See Repair the agent.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The operation needs the guest’s root agent.

Cause: The request reached a PommeAgent process that doesn’t run as root. Pomme sends privileged requests only to the root agent, so this is a bug in Pomme.

Resolution:

  1. Run pomme agent repair NAME to reinstall the agent.
  2. If the failure continues, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The guest agent didn’t respond in time.

Cause: PommeAgent didn’t reply before the time limit, often because the guest is busy or still starting.

Resolution:

  1. Retry with a larger --timeout value.
  2. Run pomme status NAME to check the agent’s connection.

The guest agent isn’t connected.

Cause: PommeAgent runs inside the guest and connects to the host after macOS starts. It hasn’t connected yet, or it isn’t installed.

Resolution:

  1. Wait for the guest to finish starting; pomme status NAME reports when the agent connects.
  2. If it never connects, see Repair the agent.

A guest agent update is waiting to finish.

Cause: A new PommeAgent was installed and is waiting to activate.

Resolution: Run pomme agent update NAME to finish the update, or restart the guest.

The guest agent rejected the host’s credential.

Cause: The credential that the host presented doesn’t match the agent’s, or it expired.

Resolution:

  1. Run pomme agent status NAME.
  2. See Repair the agent to reinstall the agent’s credential.

The command doesn’t exist in the guest.

Cause: The executable that you gave to pomme exec isn’t at that path in the guest, or isn’t in the guest’s PATH.

Resolution:

  1. Give the full path of the executable, such as /usr/bin/sw_vers.
  2. Check the path with pomme exec NAME -- /bin/ls -l PATH.

The guest doesn’t support the feature.

Cause: The installed PommeAgent doesn’t support the feature.

Resolution: Update the agent with pomme agent update NAME, or configure the feature in the guest.

Pomme couldn’t verify the end of a file replacement in the guest.

Cause: The new file is in place, but PommeAgent couldn’t confirm that it removed the previous file from the staging path. A leftover staging file might remain next to the destination.

Resolution:

  1. Check the destination’s directory in the guest and remove any leftover staging file.
  2. Run pomme cat NAME PATH to confirm the destination’s contents.

The file transfer failed.

Cause: Copying a file between the host and the guest stopped partway. The message gives the reason and how many bytes were copied.

Resolution: Read the reason in the message, then retry the copy.

The guest agent rejected the request.

Cause: PommeAgent rejected a value in the request. The message gives the reason.

Resolution:

  1. Correct the value that the message names.
  2. If you didn’t give the value, update the agent with pomme agent update NAME.

A guest file operation failed.

Cause: PommeAgent couldn’t read or write a file in the guest. The message gives the path and reason.

Resolution: Check the path, its permissions, and the guest’s free disk space.

The guest job doesn’t exist.

Cause: No detached guest job has the ID that you gave. Jobs end when the guest restarts.

Resolution: Run pomme jobs list NAME to see the VM’s jobs.

The guest couldn’t complete the MDM operation.

Cause: PommeAgent couldn’t enroll, observe, or clean up an MDM profile in the guest. The message gives the step that failed.

Resolution:

  1. Read the step in the message.
  2. Run pomme log NAME --last 5m to see the guest’s log, then retry pomme mdm.

The guest’s MDM enrollment helper failed.

Cause: The temporary helper that installs the MDM profile in the guest rejected its request, files, or code signature, or the enrollment failed.

Resolution:

  1. Read the reason in the message.
  2. Retry pomme mdm. If the failure continues, run pomme bug-report NAME and attach the file to a new issue.

The guest couldn’t list its MDM profiles.

Cause: The guest’s profiles command failed, returned too much output, or didn’t exit.

Resolution:

  1. Retry the command.
  2. Run pomme log NAME --last 5m to see the guest’s log.

The MDM enrollment’s outcome is unknown.

Cause: The enrollment stopped at a point where Pomme can’t tell whether the guest installed the profile. Pomme kept the enrollment identity in place.

Resolution:

  1. Check the installed profiles in the guest’s System Settings > General > Device Management before you retry.
  2. Retry pomme mdm only when the profile isn’t installed.

The guest couldn’t stage the MDM profile.

Cause: PommeAgent keeps the MDM profile in a private, root-owned directory. The directory or the profile didn’t have the required owner and permissions, or PommeAgent couldn’t remove the staged profile.

Resolution:

  1. Retry pomme mdm.
  2. If the failure continues, run pomme agent repair NAME.

The guest MDM operation timed out.

Cause: Enrolling or checking an MDM profile in the guest didn’t finish within its time limit, often because the MDM server didn’t respond.

Resolution: Check that the guest can reach the MDM server, then retry pomme mdm.

The guest item doesn’t exist.

Cause: A file, directory, user, group, or job that the operation names doesn’t exist in the guest.

Resolution: Check the name or path in the message.

The guest couldn’t complete the operation.

Cause: PommeAgent reported a failure. The message gives the guest’s reason.

Resolution:

  1. Read the reason in the message.
  2. Run pomme log NAME --last 5m to see the guest’s log.

The guest agent doesn’t support the operation.

Cause: The installed PommeAgent is older than this pomme, or the operation isn’t available in the guest’s current boot mode.

Resolution: Update the agent with pomme agent update NAME.

The guest’s automatic-login credential can’t be used.

Cause: The automatic-login file isn’t the root-owned file that macOS writes, or Pomme couldn’t decode it.

Resolution: Turn automatic login off and on again in the guest’s System Settings > Users & Groups, then retry.

The guest has no automatic-login credential for the owner.

Cause: Pomme reads the owner’s credential from the guest’s automatic-login setting. The guest has no automatic-login account, or it’s a different account.

Resolution:

  1. Turn on automatic login for the owner account in the guest’s System Settings > Users & Groups.
  2. See Change SIP and AMFI.

The guest couldn’t install the package.

Cause: /usr/sbin/installer in the guest exited with a nonzero status while pomme install ran it. Its output, printed before the error, gives the reason.

Resolution:

  1. Read the installer output for the reason.
  2. Run pomme exec NAME -- /usr/bin/tail -n 50 /var/log/install.log to see the guest’s installation log.

The guest denied permission.

Cause: macOS in the guest refused access to a file, directory, or executable.

Resolution: Check the permissions of the path in the message, or run the operation as a user who has access.

The operation needs the Recovery agent.

Cause: A security operation reached a PommeAgent that isn’t running in macOS Recovery as root. Pomme sends these operations only to the Recovery agent, so this is a bug in Pomme.

Resolution: Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The Recovery agent couldn’t find the guest’s Data volume.

Cause: In macOS Recovery, PommeAgent needs exactly one System and Data volume pair from the expected volume group. diskutil failed, or reported none, several, or an unsafe mount.

Resolution:

  1. Stop the VM with pomme stop NAME, then retry.
  2. If the failure continues, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t verify the Recovery environment.

Cause: The guest isn’t running in an authenticated macOS Recovery, or its startup volume isn’t the one that the request named.

Resolution: Stop the VM with pomme stop NAME, then retry the command so that Pomme starts Recovery again.

The Recovery agent can’t change NVRAM.

Cause: macOS Recovery denied a write to the VM’s boot arguments, or this Recovery version hasn’t passed Pomme’s NVRAM write and read-back check.

Resolution:

  1. Run pomme amfi status NAME to check the current state.
  2. See Change SIP and AMFI.

A Recovery operation in the guest failed.

Cause: The Pomme agent in macOS Recovery couldn’t complete a security operation. The causes give its failure code.

Resolution:

  1. Run pomme sip status NAME to see the VM’s security state.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The Recovery security command timed out.

Cause: A command that the Recovery agent runs, such as csrutil, didn’t finish within its time limit.

Resolution:

  1. Retry the pomme sip or pomme amfi command.
  2. Run pomme sip status NAME to check the VM’s security state.

An earlier security change is unfinished.

Cause: A previous pomme sip or pomme amfi change stopped partway, and the Recovery agent must finish or roll it back first.

Resolution:

  1. Repeat the earlier command in the same direction so that Pomme can finish it.
  2. Run pomme amfi status NAME to see the state.

Pomme couldn’t verify the security change.

Cause: After it changed or rolled back the VM’s security settings, the Recovery agent read back a value that didn’t match.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the current state.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

guest-remote-login-full-disk-access-required

Section titled “guest-remote-login-full-disk-access-required”

Changing Remote Login needs Full Disk Access.

Cause: macOS lets a process change Remote Login only when it has Full Disk Access.

Resolution: See Enable remote access.

Pomme couldn’t verify the Remote Login change.

Cause: The guest’s Remote Login setting didn’t match the requested value after the change.

Resolution: Check Remote Login in the guest’s Sharing settings, then retry.

The guest couldn’t update its Setup Assistant preferences.

Cause: PommeAgent skips Setup Assistant screens by writing the owner’s preferences. It couldn’t find the owner account, or reading or writing a preference file failed.

Resolution:

  1. Restart the guest with pomme restart NAME so that PommeAgent tries again.
  2. Run pomme log NAME --last 5m to see the guest’s log.

The guest command didn’t prompt for its credential as expected.

Cause: Pomme answers a guest command’s credential prompt privately. The command exited before it prompted, didn’t prompt in time, prompted more than once, or printed too much output before its prompt.

Resolution:

  1. Retry the command.
  2. Run pomme log NAME --last 5m to see the guest’s log.

Pomme refused to send a credential to the guest command.

Cause: The guest command’s prompt didn’t match the expected prompt, or the command echoed the credential, so Pomme stopped to keep the credential private.

Resolution:

  1. Check that the guest is in the expected state, then retry.
  2. Run pomme bug-report NAME and attach the file to a new issue if the failure continues.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t confirm that the guest process stopped.

Cause: The command was interrupted, and Pomme couldn’t confirm that the guest process it started has exited.

Resolution:

  1. Run pomme jobs list NAME to look for the process.
  2. Stop it with pomme jobs kill NAME --job ID if it’s still running.

Another client is attached to the terminal session.

Cause: A terminal session accepts one attachment at a time.

Resolution: Detach the other client, or run pomme sessions attach NAME --session ID --takeover to replace it.

The terminal session doesn’t exist.

Cause: No terminal session has the ID that you gave. Sessions can end when the guest restarts or when you delete them.

Resolution: Run pomme sessions list NAME to see the VM’s sessions.

Another client took over the terminal session.

Cause: Another client attached to the session with --takeover, which ended this attachment.

Resolution: Run pomme sessions attach NAME --session ID --takeover to attach again.

The terminal session’s state doesn’t allow the operation.

Cause: The operation needs the session in a different state. For example, a session that is still running can’t be deleted.

Resolution:

  1. Run pomme sessions inspect NAME --session ID to see its state.
  2. Stop a running session with pomme sessions terminate NAME --session ID.

The terminal session store couldn’t complete the operation.

Cause: The guest’s terminal session store is unavailable, an entry in it isn’t valid, or a transcript changed outside the store.

Resolution:

  1. Run pomme sessions list NAME to check the store.
  2. If the failure continues, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Recovery terminal sessions can’t be saved.

Cause: Terminal sessions in macOS Recovery exist only while the Recovery agent runs, so their transcripts aren’t stored.

Resolution: Copy anything you need from the session before it ends.

The VM’s Pomme agent identity isn’t valid.

Cause: The provisioning plan names a Pomme agent whose role, digest, or protocol version isn’t valid.

Resolution: Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t set up the macOS owner account for the first boot.

Cause: Virtualization.framework rejected the guest provisioning options, or Pomme couldn’t record that it started them. Pomme shows only the error’s code, because the options include the owner account’s credentials.

Resolution:

  1. Run pomme create NAME --resume to retry.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

A component that the operation needs isn’t available.

Cause: The operation needs an internal component, such as an authenticated Recovery session or a verified installation receipt, that isn’t available. This is a bug in Pomme.

Resolution:

  1. Update Pomme with pomme update.
  2. If the failure continues, run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t verify the VM’s provisioning records.

Cause: Pomme signs the VM’s provisioning journal with a key in your login Keychain. The signature doesn’t match, the key isn’t available, or a record was changed outside Pomme.

Resolution:

  1. Unlock your login Keychain, then retry.
  2. If the failure continues, delete the VM with pomme delete NAME --force, then create it again. Pomme removes only the bundle and keeps the VM’s Keychain items.

The VM’s provisioning journal isn’t valid.

Cause: The journal that records each creation step has a missing value, an unknown schema, or steps in an order that isn’t valid.

Resolution:

  1. Delete the VM with pomme delete NAME --force, then create it again. Pomme removes only the bundle and keeps the VM’s Keychain items.
  2. If the journal wasn’t edited, run pomme bug-report NAME and attach the file to a new issue.

The VM’s provisioning journal is out of date.

Cause: The journal is older than the last generation that Pomme recorded, or another process changed it at the same time.

Resolution:

  1. Make sure that no other Pomme command is using the VM, then retry.
  2. If the journal was restored from a backup, delete the VM with pomme delete NAME and create it again.

Pomme couldn’t access the VM’s provisioning journal safely.

Cause: The journal file or its directory is missing, is a symbolic link, is readable by other users, or couldn’t be written.

Resolution:

  1. Run Pomme as the user who created the VM, not with sudo.
  2. Check the permissions of the VM bundle with pomme inspect NAME.

The VM’s agent doesn’t need repair.

Cause: Agent provisioning is complete. pomme agent repair doesn’t reconcile SIP or AMFI security transactions.

Resolution: Run pomme agent status NAME to check the agent.

The VM doesn’t match its provisioning records.

Cause: Pomme acts only on the exact VM that it created. The VM bundle’s identity, location, or name doesn’t match the records that Pomme kept, usually because the bundle was moved, copied, or replaced.

Resolution:

  1. Run pomme list to check the VM.
  2. Move the bundle back if you moved it.
  3. Otherwise, delete the VM with pomme delete NAME --force, then create it again. Because Pomme can’t prove which VM the bundle is, it removes only the bundle and keeps the VM’s Keychain items.

A step of VM creation failed.

Cause: Creation is a journaled workflow. A step, such as installing macOS or the Pomme agent, failed after it started. Pomme kept the VM and its journal so that you can resume. The error’s causes give the step’s reason, such as a full disk.

Resolution:

  1. Read the reason in the message and correct it.
  2. Run pomme create NAME --resume to continue from the first unfinished step.
  3. To start over instead, run pomme delete NAME, then create the VM again.

A step of VM creation was interrupted.

Cause: A creation step started but didn’t record a result, and repeating it isn’t safe. For example, repeating the first boot could create a second owner account.

Resolution:

  1. Run pomme agent status NAME to see the VM’s workflow.
  2. Delete the VM with pomme delete NAME, then create it again.

The VM’s provisioning plan isn’t valid.

Cause: The plan that records how Pomme creates the VM is missing a value, or it’s a plan that this version of Pomme doesn’t accept.

Resolution:

  1. If a newer version of Pomme created the VM, update Pomme with pomme update.
  2. Otherwise, delete the VM with pomme delete NAME, then create it again.

Agent repair can’t continue VM creation.

Cause: The VM’s creation stopped at a step that pomme agent repair doesn’t handle.

Resolution: Run pomme create NAME --resume to continue creation.

The guest bootstrap command failed.

Cause: A command that Pomme runs to install the Pomme agent over SSH couldn’t start or exited with an error.

Resolution:

  1. Run pomme create NAME --resume to retry.
  2. Run pomme log NAME --last 5m to see the guest’s log.

Pomme couldn’t verify the guest bootstrap.

Cause: While it installs the Pomme agent over SSH, Pomme checks the guest’s network lease, host key, and staged files. One of them was missing, ambiguous, or didn’t match.

Resolution:

  1. Run pomme create NAME --resume to retry.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

The guest bootstrap command timed out.

Cause: A command that Pomme runs to install the Pomme agent over SSH didn’t finish in time. The guest might still be finishing its first boot.

Resolution: Run pomme create NAME --resume to retry.

Cloning the template failed.

Cause: Pomme couldn’t copy the template’s files into the new VM bundle. The error’s causes give the reason, such as a full disk.

Resolution:

  1. Read the reason in the message and correct it.
  2. Free space on the volume that holds your VMs if it’s full, then retry.

The disk size doesn’t match the template.

Cause: A VM cloned from a template keeps the template’s disk size, and --disk-size asked for a different size.

Resolution:

  1. Omit --disk-size to use the template’s size.
  2. To use another size, create a template with that size.

A template with that name already exists.

Cause: Pomme doesn’t replace an installed template.

Resolution: Choose another name, or delete the template with pomme template delete NAME, then retry.

The template is incomplete.

Cause: The template bundle is missing its disk image, auxiliary storage, or hardware model.

Resolution: Delete the template with pomme template delete NAME, then create it again with pomme template create NAME.

The template’s manifest isn’t valid.

Cause: The template’s Template.json file is missing, can’t be read, or has a value that isn’t valid.

Resolution: Delete the template with pomme template delete NAME, then create it again with pomme template create NAME.

The template doesn’t exist.

Cause: No installed template has the name that you gave.

Resolution:

  1. Run pomme template list to see your templates.
  2. Create the template with pomme template create NAME --latest.

The VM’s pinned agent isn’t on this Mac.

Cause: A Recovery repair or resumed creation installs exactly the agent that the VM was created with. Pomme keeps a copy when it creates a VM, and that copy is missing.

Resolution: Reinstall the Pomme build that created the VM, then retry.

The pinned agent copy isn’t valid.

Cause: The retained agent isn’t a private regular file, changed while Pomme read it, or doesn’t match the digest that the VM pins.

Resolution:

  1. Reinstall the Pomme build that created the VM, then retry.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

The agent’s code signature isn’t trusted.

Cause: Pomme installs only an agent that has Pomme’s Developer ID signature. The executable doesn’t have it, or the signature isn’t valid.

Resolution: Install a signed Pomme release with pomme update or from https://pommevm.dev, then retry.

The agent artifact store isn’t available.

Cause: Pomme keeps a copy of each agent that it installs in ~/Library/Application Support/pomme/AgentArtifacts. The directory is missing, isn’t yours, or is writable by other users.

Resolution: Make sure that the directory and its parent directories belong to you and aren’t writable by other users, then retry.

Pomme couldn’t save a copy of its agent.

Cause: Pomme couldn’t write the copy of its executable that it keeps for later agent repairs. The message gives the reason.

Resolution: Read the reason in the message and correct it, then retry.

Pomme refused a guest agent connection.

Cause: A guest agent connected with a role or session that doesn’t match the operation in progress. This is a bug in Pomme or a sign that the guest isn’t the expected one.

Resolution:

  1. Retry the command.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

No session is ready for the guest agent’s connection.

Cause: A guest agent connected for a Recovery operation before Pomme prepared its session, or after the session ended.

Resolution: Retry the command.

The VM’s agent credential isn’t valid.

Cause: The VM’s agent credential in your login Keychain has an invalid format or type.

Resolution: Run pomme agent repair NAME to reinstall the agent and its credential.

The VM’s agent credential isn’t in the Keychain.

Cause: Pomme authenticates to the VM’s agent with a credential in your login Keychain, and the item is missing.

Resolution:

  1. Make sure that you’re signed in as the user who created the VM.
  2. Run pomme agent repair NAME to reinstall the agent and its credential.

A newer guest agent connection replaced this one.

Cause: The guest agent reconnected, for example after it restarted, while an operation used the previous connection.

Resolution: Retry the command.

The updated agent didn’t connect in time.

Cause: The new agent is installed, but the running agent didn’t restart with it in time. It takes effect when the VM restarts.

Resolution: Run pomme restart NAME, then run pomme agent update NAME again to record the update.

Background jobs or terminal sessions block the agent update.

Cause: Restarting the agent would leave running jobs and terminal sessions without a manager.

Resolution:

  1. Let the jobs and sessions finish, or stop them with pomme jobs kill NAME --job ID and pomme sessions terminate NAME --session ID.
  2. Run pomme agent update NAME again.

The guest couldn’t install the new agent.

Cause: The guest couldn’t make the new agent executable or install it. The previous agent is still installed.

Resolution:

  1. Run pomme agent update NAME again.
  2. If it fails again, run pomme agent repair NAME to reinstall the agent that the VM was created with.

A retained workflow blocks the agent update.

Cause: A SIP, AMFI, or MDM enrollment operation on the VM hasn’t finished, and it depends on the current agent.

Resolution: Finish or repeat the retained operation, then run pomme agent update NAME again.

The copied agent doesn’t match this host’s Pomme.

Cause: After Pomme copied its executable into the guest, the copy’s digest didn’t match the original.

Resolution:

  1. Run pomme agent update NAME again.
  2. If it fails again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM has no Pomme agent to update.

Cause: pomme agent update updates only an agent that Pomme installed when it created the VM.

Resolution: Run pomme agent status NAME to see the VM’s agent workflow.

The VM’s agent can’t be updated in place.

Cause: The agent in the VM is too old to receive files or run processes.

Resolution: Run pomme agent repair NAME to reinstall the agent from Recovery.

Pomme couldn’t verify its own executable.

Cause: Pomme reads and digests its own executable so that it can pin the exact agent that it installs in a VM. The file is missing, isn’t a regular file, or couldn’t be read.

Resolution:

  1. Make sure that the pomme executable exists and is readable.
  2. Reinstall Pomme with pomme update, then retry.

Restoring the snapshot failed.

Cause: The VM helper exited before it restored the snapshot and paused the VM.

Resolution:

  1. Run pomme stop NAME, then run pomme snapshot restore NAME --snapshot SNAPSHOT again.
  2. Run pomme bug-report NAME to collect the helper log if it fails again.

Restoring the snapshot timed out.

Cause: The VM helper didn’t restore the snapshot and pause the VM in time.

Resolution: Run pomme stop NAME, then run pomme snapshot restore NAME --snapshot SNAPSHOT again.

The update command failed.

Cause: The command that installs the update, such as brew upgrade or the install script, exited with an error.

Resolution: Read the command’s output for the reason, correct it, then run pomme update again.

Pomme couldn’t find the newest release.

Cause: The request to the release feed failed, or its reply couldn’t be read.

Resolution: Check the network connection, then run pomme update again.

No Pomme release is published for this install.

Cause: The release feed for the channel that this installation follows doesn’t list a release yet.

Resolution: Retry later, or install the newest alpha as the message describes.

A build from source can’t update itself.

Cause: pomme update updates only an install from Homebrew, the install script, the installer package, or the release tarball.

Resolution: Pull the newest source and run bash Scripts/build-local.sh.

This Pomme’s version isn’t a release version.

Cause: pomme update compares release versions, and this executable reports a version that isn’t one.

Resolution: Install a Pomme release from https://pommevm.dev.

The installed version isn’t the expected one.

Cause: The update command succeeded, but the installed pomme reports a different version than the release that it installed.

Resolution:

  1. Run pomme --version to check the version.
  2. Check that command -v pomme resolves to the installed path, then run pomme update again.

Pomme’s VM lock isn’t valid.

Cause: The lock that a command holds for a VM was released early, belongs to another VM, or couldn’t be passed to the VM helper. This is a bug in Pomme.

Resolution:

  1. Retry the command.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t open the VM’s lock file safely.

Cause: Pomme keeps a lock file for each VM so that two commands don’t change it at once. The file isn’t a regular file, or it has the wrong owner or permissions.

Resolution: Run Pomme as the user who created the VM, not with sudo, then retry.

Another Pomme command is changing the VM.

Cause: Pomme lets one command at a time create, start, stop, restore, update, or delete a VM.

Resolution: Wait for the other command to finish, then retry.

Pomme has no recorded AMFI baseline to restore.

Cause: pomme amfi enable restores the exact boot policy and boot arguments that Pomme recorded before it turned off AMFI. No recording exists for this VM, and Pomme doesn’t guess one.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. See Change SIP and AMFI.

Changing AMFI requires SIP to be off.

Cause: Pomme writes and verifies AMFI boot arguments only while SIP is off.

Resolution:

  1. Run pomme sip disable NAME first.
  2. Restore AMFI with pomme amfi enable NAME before you turn SIP on again.
  3. See Change SIP and AMFI.

The VM’s guest agent doesn’t support this workflow.

Cause: The Pomme agent in the VM is older than this pomme and lacks a capability that the SIP or AMFI workflow needs. Pomme doesn’t replace the agent during the workflow.

Resolution:

  1. Run pomme agent update NAME to install the current agent, then retry.
  2. If the update isn’t possible, create a new VM with this version of Pomme.

Pomme couldn’t authenticate the guest agent.

Cause: SIP and AMFI changes use the guest agent that Pomme installed when it created the VM. The agent didn’t answer, or it didn’t prove the identity that Pomme recorded for it.

Resolution:

  1. Run pomme agent status NAME to check the agent.
  2. Run pomme agent repair NAME if the agent is missing or damaged, then retry.

macOS refused automatic login for the owner.

Cause: The workflow signs in the owner automatically so that it can verify changes after a restart. macOS refused, for example because FileVault, Touch ID, Apple Pay, App Store purchase protection, or a management policy is on.

Resolution:

  1. Turn off the setting that the message names in the guest, then repeat the same command.
  2. See Change SIP and AMFI.

Pomme couldn’t verify the security change.

Cause: After Pomme changed SIP or AMFI, it read the setting again and couldn’t confirm the requested value. Pomme keeps the workflow’s progress so that the next attempt can inspect it.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

A guest command didn’t finish cleanly.

Cause: A command that Pomme ran in the guest during the security workflow timed out, was cancelled, or returned incomplete output. Pomme keeps its progress.

Resolution: Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

The owner credential’s Keychain item belongs to something else.

Cause: The Keychain item that Pomme uses for this VM’s owner already exists and belongs to another VM or wasn’t created by Pomme. Pomme doesn’t overwrite it.

Resolution: Open Keychain Access, find the item that names the VM’s UUID, and remove it if you no longer need it.

The stored owner credential can’t be used.

Cause: Pomme keeps the guest owner’s credential in your login Keychain. The item, or the reference to it in the journal, isn’t in the format that Pomme writes.

Resolution: Provide the owner’s credentials another way. See Change SIP and AMFI.

Pomme couldn’t confirm that the guest desktop is ready.

Cause: Pomme waits for the owner’s desktop session before it continues. The guest agent didn’t report a ready desktop. The message names the step that failed.

Resolution: Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

The security workflow journal can’t be used.

Cause: Pomme records each SIP and AMFI step in a journal in the VM bundle. The journal is missing, too large, has unsafe permissions, belongs to another VM, or is damaged.

Resolution:

  1. Check that the VM bundle’s files are owned by your account and aren’t writable by others.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t save the security workflow journal.

Cause: Pomme writes and synchronizes the journal before each step so that it can resume after an interruption. Writing or synchronizing the file failed.

Resolution:

  1. Check that the volume that holds the VM has free space and is writable.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

Another security operation is unfinished.

Cause: An earlier SIP or AMFI operation on this VM didn’t finish, and Pomme doesn’t start a different one until it does.

Resolution: Repeat the earlier operation’s command with the same --final-state value to finish it. See Change SIP and AMFI.

An account with the owner’s name already exists.

Cause: The guest already has an account with the name that Pomme uses for the owner, and Pomme can’t prove that it’s the account it created earlier.

Resolution: Provide that account’s credentials, or remove the account in the guest. See Change SIP and AMFI.

Pomme couldn’t confirm that the owner signed in.

Cause: After a normal restart, the guest didn’t show the owner’s desktop within the time limit. Pomme keeps the account, its credential, and the workflow’s progress.

Resolution: Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

Pomme can’t create an owner account on this VM.

Cause: Pomme creates the guest owner only on a VM that it created and that it can prove has no other user accounts or earlier provisioning. This VM didn’t pass that check.

Resolution: Provide the existing owner’s credentials. See Change SIP and AMFI.

Pomme couldn’t prepare the owner account.

Cause: A step that creates, checks, or signs in the guest owner failed or returned evidence that Pomme couldn’t verify. Pomme keeps the account and its progress.

Resolution:

  1. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.
  2. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

Pomme couldn’t verify the owner account.

Cause: The guest didn’t accept the owner’s credentials, or the account isn’t an administrator that owns the startup volume.

Resolution:

  1. Check the user name and credential that you provided.
  2. See Change SIP and AMFI.

Pomme couldn’t pass the owner’s credential to a guest command.

Cause: Some guest commands read the owner’s credential from a private terminal. The command didn’t show the expected prompt, echoed its input, or exited early, so Pomme stopped without retrying the credential.

Resolution:

  1. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.
  2. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

Pomme couldn’t verify the guest restart.

Cause: To apply a change, Pomme restarts the guest and checks that it booted again with a new boot session. The restart request, the stop, the start, or the check afterward failed. Pomme keeps the workflow’s progress.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

A security command in Recovery failed.

Cause: The Pomme agent in macOS Recovery ran csrutil, bputil, or nvram, and the command failed, timed out, or showed an unexpected prompt. Pomme keeps the workflow’s progress so that the next attempt can inspect it.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

The command doesn’t match the unfinished security operation.

Cause: The VM has an unfinished SIP or AMFI operation, and the command asks for a different action or final state. Pomme can’t change a retained operation.

Resolution: Repeat the original command exactly, with the same action and --final-state value. See Change SIP and AMFI.

Pomme couldn’t restore the VM’s run state.

Cause: After the security workflow, Pomme couldn’t prove that cleanup finished or that the VM returned to the requested final state. Pomme keeps the owner account, its credential, and the workflow’s progress.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.

Pomme couldn’t verify the rollback of a security change.

Cause: A security change failed, and Pomme couldn’t confirm that it restored the recorded boot policy and NVRAM values. Pomme keeps the workflow’s progress.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Repeat the same pomme sip or pomme amfi action with the same --final-state value to resume. See Change SIP and AMFI.
  3. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM’s security state doesn’t allow this step.

Cause: The security state file records a step that conflicts with the requested one, for example because a restoration isn’t verified yet. This is a bug in Pomme.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM’s security state file can’t be used.

Cause: The security state file in the VM bundle is damaged, uses an unsupported format, isn’t private to your account, or belongs to another VM.

Resolution:

  1. Check that the VM bundle’s files are owned by your account and aren’t writable by others.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM’s security state is too old to resume.

Cause: Pomme resumes a security restoration only within 24 hours of the state that it recorded.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Run the SIP or AMFI command again to start a new operation.

Pomme couldn’t save the VM’s security state.

Cause: Writing or removing the security state file in the VM bundle failed. The causes give the reason.

Resolution: Check that the volume that holds the VM has free space and is writable, then retry.

Pomme couldn’t verify the VM’s security state.

Cause: Pomme reads the SIP and AMFI state from the guest and accepts only a reply that it can parse exactly. The reply was missing, incomplete, or in an unexpected format.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Run pomme agent status NAME to check that the guest agent is connected.

Pomme couldn’t start its agent in Recovery.

Cause: Pomme starts a Pomme agent in macOS Recovery through Recovery’s Terminal. The agent didn’t start, didn’t authenticate, or stopped responding.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Stop the VM with pomme stop NAME, then run the same command again.
  3. Run the command with --debug to save screenshots of each Recovery step.

The Recovery agent didn’t authenticate.

Cause: The Pomme agent that runs in macOS Recovery proves its identity with a one-time credential that expires after a few minutes. The credential expired, was already used, or didn’t match.

Resolution:

  1. Run the same command again. Each attempt starts a new Recovery session.
  2. If the VM is slow to reach Recovery, stop other VMs to free memory and CPU, then retry.

Pomme couldn’t confirm that Recovery cleanup finished.

Cause: After a Recovery operation, Pomme removes the files and directory share that it staged and detaches any disk image. It couldn’t confirm that every item was removed, so it didn’t change the VM’s final state.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Stop the VM with pomme stop NAME, then run the same command again; Pomme cleans up the earlier session first.

Pomme couldn’t confirm the VM’s final state.

Cause: After the Recovery operation, Pomme asked the VM to reach the requested final state, such as stopped or running normally, and couldn’t confirm that it did.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Start or stop the VM yourself with pomme start NAME or pomme stop NAME.

Pomme couldn’t verify the agent it copies into Recovery.

Cause: Pomme copies its own signed executable into macOS Recovery. The code signature, digest, or file identity of that copy didn’t match the running pomme, or it changed while Pomme read it.

Resolution:

  1. Reinstall Pomme with pomme update, then run the command again.
  2. If you built Pomme yourself, sign it with the same identity as the installed build.

The Recovery operation didn’t finish.

Cause: The Pomme agent in macOS Recovery didn’t complete the requested operation. The causes give the reason when one is known.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Run the same command again. Each attempt starts a new Recovery session.
  3. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme rejected its own Recovery request.

Cause: Before Pomme starts macOS Recovery, it binds the request to one VM, one executable, and one operation. A value in that binding was missing, out of range, or didn’t match the VM. This is a bug in Pomme.

Resolution:

  1. Run the same command again. Each attempt starts a new Recovery session.
  2. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t read the VM’s run state.

Cause: Before Pomme starts Recovery, it records whether the VM is running, paused, or stopped so that it can restore that state. It couldn’t read the state.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Run the command again after the VM finishes starting or stopping.

Recovery reported a security state that Pomme can’t use.

Cause: The boot policy, NVRAM values, or recorded security baseline that the Recovery agent read or was asked to write didn’t pass validation, so Pomme didn’t change it.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the VM’s security state.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The Recovery session reached an unexpected state.

Cause: A Recovery session runs its steps in a fixed order and is used once. A step ran out of order, the session was reused, or its directory share was already attached. This is a bug in Pomme.

Resolution:

  1. Stop the VM with pomme stop NAME, then run the same command again.
  2. Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The Recovery staging directory isn’t private.

Cause: Pomme stages files for macOS Recovery in a directory that only your account can write. The directory, or a file in it, has other permissions, another owner, or an unexpected file.

Resolution:

  1. Check the ownership and permissions of the VM bundle with ls -la.
  2. Run Pomme as the user who created the VM, not with sudo.

A Recovery step didn’t finish in time.

Cause: macOS Recovery didn’t reach the expected screen, the Recovery agent didn’t connect, or a Recovery command didn’t finish within its time limit.

Resolution:

  1. Run pomme status NAME to see the VM’s state.
  2. Stop the VM with pomme stop NAME, then run the same command again.
  3. Stop other VMs to free memory and CPU if the VM is slow.

Pomme couldn’t verify the Recovery workspace.

Cause: The Recovery agent reported a workspace, disk attachment, or volume that doesn’t match what Pomme prepared, so Pomme stopped before it changed anything.

Resolution:

  1. Stop the VM with pomme stop NAME, then run the same command again.
  2. If it happens again, run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t verify the guest agent for MDM enrollment.

Cause: MDM enrollment runs only through an authenticated, attested PommeAgent that uses protocol version 1, has the enrollment and maintenance capabilities, and matches the signed executable that Pomme recorded for the VM.

Resolution:

  1. Run pomme agent status NAME to check the agent.
  2. If the agent is out of date, run pomme agent update NAME, then retry pomme mdm.
  3. If the agent still lacks the MDM capabilities, recreate the VM with a current Pomme build. See Enroll in MDM.

Pomme couldn’t remove the staged MDM files.

Cause: Pomme removes the staged profile and the enrollment helper from the guest after enrollment. A removal or verification step failed. The enrollment might have finished, and Pomme kept the VM’s state.

Resolution: Retry pomme mdm with the same arguments to finish cleanup and restoration.

Pomme can’t downgrade the MDM enrollment.

Cause: The VM’s enrollment is already user approved or supervised, and --enrollment-mode unapproved would remove that.

Resolution: Run pomme mdm without --enrollment-mode unapproved.

The VM’s MDM enrollment conflicts with the profile.

Cause: The guest already has an enrollment profile or MDM server that differs from the profile that you supplied.

Resolution:

  1. Supply the profile that the VM is enrolled with, or enroll a different VM.
  2. See Enroll in MDM.

MDM enrollment failed in the VM.

Cause: The guest couldn’t install the enrollment profile, or its reply about the installation wasn’t valid. Pomme kept the VM’s current state and the staged files so that the command can resume.

Resolution:

  1. Run pomme mdm NAME --profile PATH --debug --format json to see the failure stage and diagnostics.
  2. Check that the guest can reach the MDM server, then retry pomme mdm with the same arguments.

The MDM enrollment’s outcome is unknown.

Cause: Pomme sent the enrollment to the guest but didn’t receive a verified result, so the profile might be installed. Pomme doesn’t install the profile again without evidence that the first attempt didn’t.

Resolution:

  1. Retry pomme mdm with the same arguments. Pomme checks the guest’s enrollment before it does anything else.
  2. Check the installed profiles in the guest’s System Settings > General > Device Management.

Pomme couldn’t verify the MDM enrollment.

Cause: After enrollment, Pomme checks the guest’s installed profile, enrollment status, user approval, and supervision. The guest’s report was missing, malformed, or inconsistent, or it didn’t show the enrollment mode that you requested.

Resolution:

  1. Retry pomme mdm with the same arguments.
  2. Check the installed profiles in the guest’s System Settings > General > Device Management.

Pomme couldn’t confirm that the MDM helper stopped.

Cause: The temporary enrollment helper in the guest didn’t report that it exited, so Pomme kept its staged files and didn’t restore the VM’s security settings.

Resolution:

  1. Check that no enrollment helper process is still running in the guest, for example with pomme exec NAME -- /bin/ps -ax.
  2. Retry pomme mdm with the same arguments to finish the enrollment.

The MDM enrollment journal changed unexpectedly.

Cause: The journal on disk no longer matched the copy that Pomme was updating, which means another process changed it.

Resolution: Make sure that no other pomme command is running for the VM, then retry pomme mdm.

An unfinished MDM enrollment uses different values.

Cause: The VM has an unfinished enrollment for a different VM, profile, --enrollment-mode, or --final-security value. Pomme finishes one enrollment before it starts another.

Resolution: Repeat pomme mdm with the original profile, --enrollment-mode, and --final-security values to finish it.

The MDM enrollment journal is damaged.

Cause: Pomme records MDM progress in MDMEnrollmentJournal.json in the VM bundle. The file isn’t valid JSON for its schema, is too large, or isn’t a private regular file that you own.

Resolution:

  1. If you edited or copied the file, restore it.
  2. If the journal came from a newer Pomme build, install that build to finish the enrollment.
  3. Otherwise, run pomme bug-report NAME and attach the file to a new issue.

The MDM enrollment can’t resume from its recorded state.

Cause: The journal records a phase that the requested step can’t follow, or Pomme tried to change it without holding the VM’s lock. This is a bug in Pomme.

Resolution: Run pomme bug-report NAME and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t save the MDM enrollment journal.

Cause: Writing, flushing, or replacing MDMEnrollmentJournal.json in the VM bundle failed. The message names the step and the reason that macOS gave.

Resolution:

  1. Free space on the volume that holds your VMs if it’s full.
  2. Check the ownership and permissions of the VM bundle, then retry pomme mdm.

An unfinished operation owns this VM.

Cause: An earlier pomme mdm, pomme sip, or pomme amfi command stopped before it finished, and its journal must finish first.

Resolution:

  1. Repeat the original command with its original arguments to finish it.
  2. Then retry pomme mdm.

An MDM preparation step didn’t take effect.

Cause: A step that pomme mdm ran, such as creating the VM or finishing a SIP or AMFI change, reported success, but the VM didn’t reach the state that the step should produce.

Resolution:

  1. Run pomme mdm NAME --profile PATH --dry-run to see the detected state.
  2. Retry pomme mdm with the same arguments to resume.

Pomme couldn’t copy the MDM profile to the VM.

Cause: The copy to the guest’s private staging directory failed, or the copy’s size or digest didn’t match the profile on the host.

Resolution:

  1. Run pomme status NAME to check that the VM and its guest agent are running.
  2. Retry pomme mdm with the same arguments.

Pomme couldn’t read the MDM enrollment profile.

Cause: The --profile path doesn’t exist, isn’t a regular file, is a symbolic link, has more than one hard link, or isn’t readable. Pomme reads only a single, regular .mobileconfig file.

Resolution:

  1. Check that --profile names a regular .mobileconfig file that you can read.
  2. If the profile is a link, give the path of the file that it points to.

Pomme couldn’t restore the VM after MDM enrollment.

Cause: Pomme couldn’t restore and verify the original SIP and AMFI settings or run state. The enrollment might have finished.

Resolution:

  1. Retry pomme mdm with the same arguments to resume restoration from its journal.
  2. Run pomme sip status NAME and pomme amfi status NAME to check the settings.

Pomme couldn’t read the VM’s security settings before MDM enrollment.

Cause: Before it enrolls, Pomme records the VM’s System Integrity Protection (SIP) and Apple Mobile File Integrity (AMFI) settings and its run state so that it can restore them. The guest didn’t report them in the expected form, or SIP and AMFI weren’t turned off as the enrollment helper requires.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to check the settings.
  2. Retry pomme mdm with the same arguments.

Pomme can’t restore the VM’s original security settings exactly.

Cause: The VM’s SIP or AMFI configuration is one that Pomme can’t reproduce after enrollment, so Pomme stopped before it changed any security setting.

Resolution:

  1. Run pomme sip status NAME and pomme amfi status NAME to see the current settings.
  2. Set SIP and AMFI to a standard configuration with pomme sip and pomme amfi, then retry pomme mdm. See Change SIP and AMFI.

Pomme couldn’t prepare MDM staging in the VM.

Cause: The guest agent couldn’t create or verify the private, root-owned directory that holds the profile and the enrollment helper.

Resolution:

  1. Retry pomme mdm with the same arguments.
  2. If the failure continues, run pomme agent repair NAME.

Pomme couldn’t read the VM display.

Cause: A frame from the VM display was blank, had the wrong size, or couldn’t be decoded. A blank frame is normal while the VM starts.

Resolution:

  1. Wait for the VM to finish starting, then retry.
  2. If the error continues, run pomme bug-report and attach the file to a new issue.

The VM display didn’t send a frame in time.

Cause: Pomme waited for the VM to draw its screen, and no frame arrived before the time limit. This can happen while the VM is still starting.

Resolution:

  1. Wait for the VM to finish starting, then retry.
  2. Retry with a larger --timeout value.

The VM display has an unsupported size.

Cause: Pomme automates only a VM display of 1280 by 800 pixels, the size that Pomme gives the VMs it creates.

Resolution:

  1. Run pomme inspect NAME to check the display configuration.
  2. Create a new VM with pomme create NAME, which uses the supported size.

Input to the VM was interrupted.

Cause: The VM’s input devices changed or went away while Pomme was sending keys or pointer events. Some input might have reached the VM.

Resolution:

  1. Take a screenshot with pomme ui screenshot to check the VM’s screen.
  2. Retry the command.

Input to the VM timed out.

Cause: The VM didn’t accept the keys or pointer events before the time limit. Some input might have reached the VM.

Resolution:

  1. Take a screenshot with pomme ui screenshot to check the VM’s screen.
  2. Retry with a larger --timeout value.

The VM keyboard or pointer isn’t available.

Cause: The running VM doesn’t accept keyboard or pointer input yet, or its input devices don’t match the ones that Pomme configures.

Resolution:

  1. Wait for the VM to finish starting, then retry.
  2. Restart the VM with pomme restart NAME, then retry.

Pomme can’t use this Mac’s VM display interface.

Cause: Pomme reads the VM screen and sends keyboard and pointer input through an interface in Virtualization.framework that only some macOS versions provide. The version on this Mac doesn’t match any version that Pomme supports. This is a bug in Pomme or a macOS change that Pomme doesn’t support yet.

Resolution:

  1. Update Pomme with pomme update, then retry.
  2. If the error continues, run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

The VM display isn’t ready yet.

Cause: The VM is still starting and hasn’t published its display or input devices.

Resolution:

  1. Wait for the VM to finish starting, then retry.
  2. Run pomme status NAME to check the VM’s state.

The VM display isn’t available.

Cause: The running VM has no display that Pomme can read, or the display went away during the operation.

Resolution:

  1. Run pomme status NAME to check that the VM is running.
  2. Restart the VM with pomme restart NAME, then retry.

Pomme couldn’t save a Recovery debug screenshot.

Cause: With --debug, Pomme saves a screenshot before each Recovery action. Encoding or writing one failed. Navigation continues without it.

Resolution: Check that the host’s temporary directory has free space and is writable.

Recovery needs cleanup before Pomme can continue.

Cause: An earlier Recovery action might have reached the VM, and Pomme couldn’t confirm its result. Pomme doesn’t send more input until the Recovery session restarts.

Resolution: Stop the VM with pomme stop NAME, then run the same command again.

The VM didn’t confirm the Recovery input.

Cause: Pomme sent a key to Recovery and couldn’t confirm that the VM received it, so Pomme stopped instead of sending it again.

Resolution: Stop the VM with pomme stop NAME, then run the same command again.

Recovery navigation stopped before it sent any input.

Cause: Pomme stopped before it sent any keys to Recovery, so the VM didn’t change.

Resolution:

  1. Run the same command again.
  2. Run the same command again with --debug to save a screenshot before each Recovery action.

Pomme couldn’t confirm that it owns the VM.

Cause: Before Pomme types into Recovery, it checks that the running VM is the one that it created. The check failed, so Pomme sent no input.

Resolution:

  1. Run pomme inspect NAME to check the VM.
  2. Stop the VM with pomme stop NAME, then retry.

The Recovery navigation profile doesn’t match its record.

Cause: The Recovery navigation profile in this Pomme build doesn’t match the reviewed record that it must match. This is a bug in Pomme.

Resolution:

  1. Update Pomme with pomme update.
  2. Run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Recovery navigation for this macOS build isn’t available yet.

Cause: Pomme recorded the Recovery screens for this macOS build, and their review isn’t finished, so Pomme doesn’t send input to them.

Resolution:

  1. Create the VM from a supported macOS version. See Requirements.
  2. Update Pomme with pomme update to get newly supported builds.

Pomme didn’t recognize the Recovery screen.

Cause: The VM showed a Recovery screen that Pomme didn’t expect, so Pomme stopped before it sent more input. Pomme keeps the VM so that you can resume.

Resolution:

  1. Run the same command again with --debug to save a screenshot before each Recovery action.
  2. See Recovery navigation stops.

The Recovery screen didn’t settle.

Cause: The VM screen kept changing, so Pomme couldn’t confirm which Recovery screen it showed. Pomme keeps the VM so that you can resume.

Resolution:

  1. Run the same command again.
  2. Run the same command again with --debug to save a screenshot before each Recovery action.

Recovery navigation ran out of order.

Cause: Pomme’s Recovery navigation tried a step out of sequence and stopped before it sent that input. This is a bug in Pomme.

Resolution:

  1. Stop the VM with pomme stop NAME, then run the same command again.
  2. Run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme couldn’t confirm that Terminal opened in Recovery.

Cause: Pomme opened Terminal in Recovery and couldn’t read the marker that proves Terminal is ready, so Pomme didn’t type a command.

Resolution:

  1. Stop the VM with pomme stop NAME, then run the same command again.
  2. Run the same command again with --debug to save a screenshot before each Recovery action.

Recovery didn’t reach the expected screen in time.

Cause: Pomme waited for a Recovery screen, and the VM didn’t show it before the time limit. The VM host might be busy.

Resolution:

  1. Run the same command again.
  2. Run the same command again with --debug to save a screenshot before each Recovery action.
  3. See Recovery navigation stops.

Recovery navigation isn’t qualified for this VM.

Cause: The VM’s macOS build, language, display size, or ownership doesn’t meet the rules for Recovery navigation, so Pomme sent no input.

Resolution:

  1. Run pomme inspect NAME to check the VM’s macOS version.
  2. See Recovery navigation stops.

Pomme refused to type a Recovery command.

Cause: A command or marker that Pomme was about to type in Recovery contains characters that Pomme can’t type safely. This is a bug in Pomme.

Resolution: Run pomme bug-report and attach the file to a new issue.

This code means that Pomme hit a failure that it doesn’t expect. Run pomme bug-report and attach the file to a new issue.

Pomme can’t navigate Recovery for this macOS build.

Cause: Pomme types into the macOS Recovery screens only for macOS builds whose screens it knows. The VM’s macOS build isn’t one of them.

Resolution: Create the VM from a supported macOS version. See Requirements.

Pomme can’t navigate Recovery in this language.

Cause: Pomme recognizes the macOS Recovery screens only in English.

Resolution: Create the VM with English as its language.