Errors
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-foundWith --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.
General
Section titled “General”config-invalid
Section titled “config-invalid”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:
- Correct the key that the message names.
- See Config file for the accepted keys.
credential-unavailable
Section titled “credential-unavailable”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:
- Run the command in an interactive terminal so that Pomme can prompt for it.
- See Change SIP and AMFI.
data-invalid
Section titled “data-invalid”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:
- If the data came from a file that you edited, restore it.
- Otherwise, run
pomme bug-reportand 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.
file-error
Section titled “file-error”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.
file-not-found
Section titled “file-not-found”A file doesn’t exist.
Cause: A file or directory that the operation needs is missing.
Resolution: Check the path in the message.
host-command-failed
Section titled “host-command-failed”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:
- Read the reason in the message and correct it.
- If the reason isn’t clear, run
pomme bug-reportand attach the file to a new issue.
host-disk-full
Section titled “host-disk-full”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:
- Free space on the volume. Each macOS VM needs as much free space as its disk size, which is at least 40 GB.
- Run
pomme listand delete VMs that you no longer need withpomme delete NAME.
host-disk-space-insufficient
Section titled “host-disk-space-insufficient”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:
- Free at least the amount that the hint names on that volume.
- Run
pomme listand delete VMs that you no longer need withpomme delete NAME. - Run
pomme create --dry-runto see the space check without creating anything.
host-file-unavailable
Section titled “host-file-unavailable”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.
host-unsupported
Section titled “host-unsupported”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.
host-update-required
Section titled “host-update-required”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.
internal-error
Section titled “internal-error”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.
invalid-arguments
Section titled “invalid-arguments”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.
invalid-request
Section titled “invalid-request”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:
- Correct the value that the message names.
- Run the command with
--helpto see the accepted values.
keychain-error
Section titled “keychain-error”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:
- Unlock your login Keychain, then retry.
- If macOS asks whether
pommecan access an item, allow it.
network-error
Section titled “network-error”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.
operation-cancelled
Section titled “operation-cancelled”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.
operation-failed
Section titled “operation-failed”The operation failed.
Cause: An operation reported a failure without a more specific code.
Resolution:
- Read the message for the reason.
- If the reason isn’t clear, run
pomme bug-reportand 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-denied
Section titled “permission-denied”Permission was denied.
Cause: macOS refused access to a file, directory, or resource.
Resolution:
- Check the ownership and permissions of the path in the message.
- Run Pomme as the user who created the VM, not with
sudo.
security-configuration-invalid
Section titled “security-configuration-invalid”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.
system-call-failed
Section titled “system-call-failed”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:
- Read the reason in the message.
- If it doesn’t explain the failure, run
pomme bug-reportand attach the file to a new issue.
system-error
Section titled “system-error”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:
- Read the reason in the message.
- If it doesn’t explain the failure, run
pomme bug-reportand attach the file to a new issue.
terminal-required
Section titled “terminal-required”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.
timed-out
Section titled “timed-out”The operation timed out.
Cause: The operation didn’t finish within its time limit.
Resolution:
- Retry with a larger
--timeoutvalue. - Run
pomme status NAMEto check that the VM is responsive.
boot-firmware-repair-failed
Section titled “boot-firmware-repair-failed”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:
- With the VM stopped, copy the backup that the message names over the
AuxiliaryStoragefile in the VM bundle. - Run
pomme bug-report NAMEand 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.
boot-firmware-unrecognized
Section titled “boot-firmware-unrecognized”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:
- Run
pomme firmware inspect NAMEto see what Pomme found. - Run
pomme bug-report NAMEand 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.
snapshot-not-found
Section titled “snapshot-not-found”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-error
Section titled “virtualization-error”Virtualization.framework reported an error.
Cause: The framework that runs the VM failed. The error’s causes give its VZErrorDomain code.
Resolution:
- Retry the operation.
- If it fails again, run
pomme bug-report NAMEand 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.
virtualization-unsupported
Section titled “virtualization-unsupported”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.
vm-bundle-damaged
Section titled “vm-bundle-damaged”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.
vm-configuration-invalid
Section titled “vm-configuration-invalid”The VM’s configuration isn’t valid.
Cause: Virtualization.framework rejected the VM’s configuration on this Mac.
Resolution:
- Run
pomme inspect NAMEto check its CPU, memory, and disk settings. - Lower the VM’s memory if it exceeds what this Mac supports.
vm-delete-refused
Section titled “vm-delete-refused”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.
vm-disk-image-invalid
Section titled “vm-disk-image-invalid”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:
- Make sure that no other process has the VM open.
- Restore the VM from a snapshot, or create it again.
vm-hardware-unsupported
Section titled “vm-hardware-unsupported”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.
vm-limit-reached
Section titled “vm-limit-reached”Too many macOS VMs are running.
Cause: macOS limits how many macOS VMs can run at the same time on one Mac.
Resolution:
- Stop another VM with
pomme stop NAME, then retry. - Run
pomme listto see which VMs are running.
vm-memory-out-of-range
Section titled “vm-memory-out-of-range”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.
vm-not-found
Section titled “vm-not-found”The VM doesn’t exist.
Cause: No Pomme VM has the name that you gave.
Resolution:
- Run
pomme listto see your VMs. - Create the VM with
pomme create NAME.
vm-not-running
Section titled “vm-not-running”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.
vm-not-specified
Section titled “vm-not-specified”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.
vm-paused-other-mode
Section titled “vm-paused-other-mode”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:
- Stop the VM with
pomme stop NAME, then start it in the boot mode that you want. - To continue in the same mode, run
pomme startwithout changing the boot mode.
vm-running
Section titled “vm-running”The VM is running.
Cause: The command needs a stopped VM.
Resolution: Stop the VM with pomme stop NAME, then retry.
vm-running-other-mode
Section titled “vm-running-other-mode”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.
vm-save-failed
Section titled “vm-save-failed”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.
vm-start-failed
Section titled “vm-start-failed”The VM couldn’t start.
Cause: Virtualization.framework failed to start the VM. The message gives its reason.
Resolution:
- Read the reason in the message.
- 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.
vm-state-invalid
Section titled “vm-state-invalid”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:
- Run
pomme status NAMEto see the VM’s state. - Change it with
pomme start,pomme stop,pomme pause, orpomme resume, then retry.
Restore images
Section titled “Restore images”macos-install-failed
Section titled “macos-install-failed”The macOS installation failed.
Cause: Virtualization.framework couldn’t install macOS from the restore image into the VM.
Resolution:
- Check that the volume has enough free space for the VM’s disk.
- 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.
restore-image-catalog-failed
Section titled “restore-image-catalog-failed”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.
restore-image-download-failed
Section titled “restore-image-download-failed”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.
restore-image-invalid
Section titled “restore-image-invalid”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.
restore-image-not-downloaded
Section titled “restore-image-not-downloaded”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.
restore-image-unknown-device
Section titled “restore-image-unknown-device”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.
restore-image-unsupported
Section titled “restore-image-unsupported”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.
VM helper
Section titled “VM helper”helper-command-failed
Section titled “helper-command-failed”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:
- Read the reason in the message.
- Run
pomme bug-report NAMEand 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.
helper-identity-unverified
Section titled “helper-identity-unverified”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.
helper-incompatible
Section titled “helper-incompatible”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.
helper-protocol-error
Section titled “helper-protocol-error”The VM helper sent an invalid reply.
Cause: A reply from the running VM’s helper was malformed or incomplete.
Resolution:
- Restart the VM with
pomme stop NAMEandpomme start NAME. - Run
pomme bug-report NAMEand 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.
helper-socket-path-too-long
Section titled “helper-socket-path-too-long”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.
helper-start-failed
Section titled “helper-start-failed”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:
- Read
pomme-helper.login the VM bundle; the message gives its path. - Run
pomme bug-report NAMEand 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.
helper-start-timed-out
Section titled “helper-start-timed-out”The VM helper didn’t start in time.
Cause: The helper process didn’t open its control socket before the time limit.
Resolution:
- Retry with a larger
--timeoutvalue. - Read
pomme-helper.login the VM bundle; the message gives its path.
helper-timed-out
Section titled “helper-timed-out”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:
- Retry with a larger
--timeoutvalue. - Run
pomme status NAMEto check that the helper is responsive.
helper-unknown-command
Section titled “helper-unknown-command”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.
Guest agent
Section titled “Guest agent”guest-agent-connecting
Section titled “guest-agent-connecting”The guest agent is still connecting.
Cause: PommeAgent is authenticating with the host.
Resolution: Retry in a moment.
guest-agent-disconnected
Section titled “guest-agent-disconnected”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.
guest-agent-launch-failed
Section titled “guest-agent-launch-failed”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:
- Run
pomme agent status NAMEto check the agent. - Run
pomme agent repair NAMEto reinstall it.
guest-agent-protocol-error
Section titled “guest-agent-protocol-error”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:
- Update the agent with
pomme agent update NAME. - 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.
guest-agent-root-required
Section titled “guest-agent-root-required”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:
- Run
pomme agent repair NAMEto reinstall the agent. - If the failure continues, run
pomme bug-report NAMEand 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-agent-timed-out
Section titled “guest-agent-timed-out”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:
- Retry with a larger
--timeoutvalue. - Run
pomme status NAMEto check the agent’s connection.
guest-agent-unavailable
Section titled “guest-agent-unavailable”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:
- Wait for the guest to finish starting;
pomme status NAMEreports when the agent connects. - If it never connects, see Repair the agent.
guest-agent-update-pending
Section titled “guest-agent-update-pending”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.
guest-authentication-failed
Section titled “guest-authentication-failed”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:
- Run
pomme agent status NAME. - See Repair the agent to reinstall the agent’s credential.
guest-command-not-found
Section titled “guest-command-not-found”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:
- Give the full path of the executable, such as
/usr/bin/sw_vers. - Check the path with
pomme exec NAME -- /bin/ls -l PATH.
guest-feature-unsupported
Section titled “guest-feature-unsupported”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.
guest-file-commit-unverified
Section titled “guest-file-commit-unverified”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:
- Check the destination’s directory in the guest and remove any leftover staging file.
- Run
pomme cat NAME PATHto confirm the destination’s contents.
guest-file-transfer-failed
Section titled “guest-file-transfer-failed”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.
guest-invalid-request
Section titled “guest-invalid-request”The guest agent rejected the request.
Cause: PommeAgent rejected a value in the request. The message gives the reason.
Resolution:
- Correct the value that the message names.
- If you didn’t give the value, update the agent with
pomme agent update NAME.
guest-io-error
Section titled “guest-io-error”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.
guest-job-not-found
Section titled “guest-job-not-found”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.
guest-mdm-failed
Section titled “guest-mdm-failed”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:
- Read the step in the message.
- Run
pomme log NAME --last 5mto see the guest’s log, then retrypomme mdm.
guest-mdm-helper-failed
Section titled “guest-mdm-helper-failed”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:
- Read the reason in the message.
- Retry
pomme mdm. If the failure continues, runpomme bug-report NAMEand attach the file to a new issue.
guest-mdm-observation-failed
Section titled “guest-mdm-observation-failed”The guest couldn’t list its MDM profiles.
Cause: The guest’s profiles command failed, returned too much output, or didn’t exit.
Resolution:
- Retry the command.
- Run
pomme log NAME --last 5mto see the guest’s log.
guest-mdm-outcome-unknown
Section titled “guest-mdm-outcome-unknown”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:
- Check the installed profiles in the guest’s System Settings > General > Device Management before you retry.
- Retry
pomme mdmonly when the profile isn’t installed.
guest-mdm-staging-failed
Section titled “guest-mdm-staging-failed”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:
- Retry
pomme mdm. - If the failure continues, run
pomme agent repair NAME.
guest-mdm-timed-out
Section titled “guest-mdm-timed-out”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.
guest-not-found
Section titled “guest-not-found”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.
guest-operation-failed
Section titled “guest-operation-failed”The guest couldn’t complete the operation.
Cause: PommeAgent reported a failure. The message gives the guest’s reason.
Resolution:
- Read the reason in the message.
- Run
pomme log NAME --last 5mto see the guest’s log.
guest-operation-unsupported
Section titled “guest-operation-unsupported”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.
guest-owner-credential-invalid
Section titled “guest-owner-credential-invalid”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.
guest-owner-credential-unavailable
Section titled “guest-owner-credential-unavailable”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:
- Turn on automatic login for the owner account in the guest’s System Settings > Users & Groups.
- See Change SIP and AMFI.
guest-package-install-failed
Section titled “guest-package-install-failed”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:
- Read the installer output for the reason.
- Run
pomme exec NAME -- /usr/bin/tail -n 50 /var/log/install.logto see the guest’s installation log.
guest-permission-denied
Section titled “guest-permission-denied”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.
guest-recovery-agent-required
Section titled “guest-recovery-agent-required”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.
guest-recovery-data-volume-unavailable
Section titled “guest-recovery-data-volume-unavailable”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:
- Stop the VM with
pomme stop NAME, then retry. - If the failure continues, run
pomme bug-report NAMEand 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-recovery-environment-unverified
Section titled “guest-recovery-environment-unverified”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.
guest-recovery-nvram-unavailable
Section titled “guest-recovery-nvram-unavailable”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:
- Run
pomme amfi status NAMEto check the current state. - See Change SIP and AMFI.
guest-recovery-operation-failed
Section titled “guest-recovery-operation-failed”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:
- Run
pomme sip status NAMEto see the VM’s security state. - Run
pomme bug-report NAMEand 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-recovery-timed-out
Section titled “guest-recovery-timed-out”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:
- Retry the
pomme siporpomme amficommand. - Run
pomme sip status NAMEto check the VM’s security state.
guest-recovery-transition-pending
Section titled “guest-recovery-transition-pending”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:
- Repeat the earlier command in the same direction so that Pomme can finish it.
- Run
pomme amfi status NAMEto see the state.
guest-recovery-verification-failed
Section titled “guest-recovery-verification-failed”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the current state. - Run
pomme bug-report NAMEand 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.
guest-remote-login-verification-failed
Section titled “guest-remote-login-verification-failed”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.
guest-setup-assistant-preferences-failed
Section titled “guest-setup-assistant-preferences-failed”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:
- Restart the guest with
pomme restart NAMEso that PommeAgent tries again. - Run
pomme log NAME --last 5mto see the guest’s log.
Guest sessions
Section titled “Guest sessions”guest-credential-prompt-failed
Section titled “guest-credential-prompt-failed”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:
- Retry the command.
- Run
pomme log NAME --last 5mto see the guest’s log.
guest-credential-prompt-refused
Section titled “guest-credential-prompt-refused”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:
- Check that the guest is in the expected state, then retry.
- Run
pomme bug-report NAMEand 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.
guest-process-cleanup-unverified
Section titled “guest-process-cleanup-unverified”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:
- Run
pomme jobs list NAMEto look for the process. - Stop it with
pomme jobs kill NAME --job IDif it’s still running.
guest-terminal-session-busy
Section titled “guest-terminal-session-busy”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.
guest-terminal-session-not-found
Section titled “guest-terminal-session-not-found”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.
guest-terminal-session-replaced
Section titled “guest-terminal-session-replaced”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.
guest-terminal-session-state-invalid
Section titled “guest-terminal-session-state-invalid”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:
- Run
pomme sessions inspect NAME --session IDto see its state. - Stop a running session with
pomme sessions terminate NAME --session ID.
guest-terminal-session-storage-failed
Section titled “guest-terminal-session-storage-failed”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:
- Run
pomme sessions list NAMEto check the store. - If the failure continues, run
pomme bug-report NAMEand 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-terminal-session-transient
Section titled “guest-terminal-session-transient”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.
Creating VMs
Section titled “Creating VMs”provisioning-agent-invalid
Section titled “provisioning-agent-invalid”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.
provisioning-dispatch-failed
Section titled “provisioning-dispatch-failed”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:
- Run
pomme create NAME --resumeto retry. - If it fails again, run
pomme bug-report NAMEand attach the file to a new issue.
provisioning-integration-unavailable
Section titled “provisioning-integration-unavailable”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:
- Update Pomme with
pomme update. - If the failure continues, run
pomme bug-reportand 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.
provisioning-journal-integrity-failed
Section titled “provisioning-journal-integrity-failed”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:
- Unlock your login Keychain, then retry.
- 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.
provisioning-journal-invalid
Section titled “provisioning-journal-invalid”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:
- Delete the VM with
pomme delete NAME --force, then create it again. Pomme removes only the bundle and keeps the VM’s Keychain items. - If the journal wasn’t edited, run
pomme bug-report NAMEand attach the file to a new issue.
provisioning-journal-stale
Section titled “provisioning-journal-stale”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:
- Make sure that no other Pomme command is using the VM, then retry.
- If the journal was restored from a backup, delete the VM with
pomme delete NAMEand create it again.
provisioning-journal-unsafe
Section titled “provisioning-journal-unsafe”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:
- Run Pomme as the user who created the VM, not with
sudo. - Check the permissions of the VM bundle with
pomme inspect NAME.
provisioning-nothing-to-repair
Section titled “provisioning-nothing-to-repair”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.
provisioning-ownership-mismatch
Section titled “provisioning-ownership-mismatch”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:
- Run
pomme listto check the VM. - Move the bundle back if you moved it.
- 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.
provisioning-phase-failed
Section titled “provisioning-phase-failed”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:
- Read the reason in the message and correct it.
- Run
pomme create NAME --resumeto continue from the first unfinished step. - To start over instead, run
pomme delete NAME, then create the VM again.
provisioning-phase-interrupted
Section titled “provisioning-phase-interrupted”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:
- Run
pomme agent status NAMEto see the VM’s workflow. - Delete the VM with
pomme delete NAME, then create it again.
provisioning-plan-invalid
Section titled “provisioning-plan-invalid”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:
- If a newer version of Pomme created the VM, update Pomme with
pomme update. - Otherwise, delete the VM with
pomme delete NAME, then create it again.
provisioning-repair-unavailable
Section titled “provisioning-repair-unavailable”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.
ssh-bootstrap-failed
Section titled “ssh-bootstrap-failed”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:
- Run
pomme create NAME --resumeto retry. - Run
pomme log NAME --last 5mto see the guest’s log.
ssh-bootstrap-invalid
Section titled “ssh-bootstrap-invalid”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:
- Run
pomme create NAME --resumeto retry. - If it fails again, run
pomme bug-report NAMEand attach the file to a new issue.
ssh-bootstrap-timed-out
Section titled “ssh-bootstrap-timed-out”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.
template-clone-failed
Section titled “template-clone-failed”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:
- Read the reason in the message and correct it.
- Free space on the volume that holds your VMs if it’s full, then retry.
template-disk-size-mismatch
Section titled “template-disk-size-mismatch”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:
- Omit
--disk-sizeto use the template’s size. - To use another size, create a template with that size.
template-exists
Section titled “template-exists”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.
template-incomplete
Section titled “template-incomplete”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.
template-manifest-invalid
Section titled “template-manifest-invalid”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.
template-not-found
Section titled “template-not-found”The template doesn’t exist.
Cause: No installed template has the name that you gave.
Resolution:
- Run
pomme template listto see your templates. - Create the template with
pomme template create NAME --latest.
Operations
Section titled “Operations”agent-artifact-missing
Section titled “agent-artifact-missing”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.
agent-artifact-rejected
Section titled “agent-artifact-rejected”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:
- Reinstall the Pomme build that created the VM, then retry.
- If it fails again, run
pomme bug-report NAMEand attach the file to a new issue.
agent-artifact-signature-rejected
Section titled “agent-artifact-signature-rejected”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.
agent-artifact-store-unavailable
Section titled “agent-artifact-store-unavailable”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.
agent-artifact-write-failed
Section titled “agent-artifact-write-failed”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.
agent-binding-invalid
Section titled “agent-binding-invalid”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:
- Retry the command.
- If it fails again, run
pomme bug-report NAMEand 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.
agent-binding-missing
Section titled “agent-binding-missing”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.
agent-credential-invalid
Section titled “agent-credential-invalid”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.
agent-credential-missing
Section titled “agent-credential-missing”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:
- Make sure that you’re signed in as the user who created the VM.
- Run
pomme agent repair NAMEto reinstall the agent and its credential.
agent-session-replaced
Section titled “agent-session-replaced”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.
agent-update-activation-timed-out
Section titled “agent-update-activation-timed-out”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.
agent-update-active-work
Section titled “agent-update-active-work”Background jobs or terminal sessions block the agent update.
Cause: Restarting the agent would leave running jobs and terminal sessions without a manager.
Resolution:
- Let the jobs and sessions finish, or stop them with
pomme jobs kill NAME --job IDandpomme sessions terminate NAME --session ID. - Run
pomme agent update NAMEagain.
agent-update-apply-failed
Section titled “agent-update-apply-failed”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:
- Run
pomme agent update NAMEagain. - If it fails again, run
pomme agent repair NAMEto reinstall the agent that the VM was created with.
agent-update-blocked
Section titled “agent-update-blocked”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.
agent-update-transfer-mismatch
Section titled “agent-update-transfer-mismatch”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:
- Run
pomme agent update NAMEagain. - If it fails again, run
pomme bug-report NAMEand 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.
agent-update-unprovisioned
Section titled “agent-update-unprovisioned”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.
agent-update-unsupported
Section titled “agent-update-unsupported”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.
executable-identity-rejected
Section titled “executable-identity-rejected”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:
- Make sure that the
pommeexecutable exists and is readable. - Reinstall Pomme with
pomme update, then retry.
snapshot-restore-failed
Section titled “snapshot-restore-failed”Restoring the snapshot failed.
Cause: The VM helper exited before it restored the snapshot and paused the VM.
Resolution:
- Run
pomme stop NAME, then runpomme snapshot restore NAME --snapshot SNAPSHOTagain. - Run
pomme bug-report NAMEto collect the helper log if it fails again.
snapshot-restore-timed-out
Section titled “snapshot-restore-timed-out”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.
update-failed
Section titled “update-failed”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.
update-lookup-failed
Section titled “update-lookup-failed”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.
update-no-release
Section titled “update-no-release”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.
update-source-build
Section titled “update-source-build”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.
update-unknown-version
Section titled “update-unknown-version”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.
update-version-mismatch
Section titled “update-version-mismatch”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:
- Run
pomme --versionto check the version. - Check that
command -v pommeresolves to the installed path, then runpomme updateagain.
vm-lock-invalid
Section titled “vm-lock-invalid”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:
- Retry the command.
- Run
pomme bug-report NAMEand 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.
vm-lock-unsafe
Section titled “vm-lock-unsafe”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.
vm-mutation-in-progress
Section titled “vm-mutation-in-progress”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.
SIP and AMFI
Section titled “SIP and AMFI”amfi-baseline-missing
Section titled “amfi-baseline-missing”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - See Change SIP and AMFI.
amfi-requires-sip-disabled
Section titled “amfi-requires-sip-disabled”Changing AMFI requires SIP to be off.
Cause: Pomme writes and verifies AMFI boot arguments only while SIP is off.
Resolution:
- Run
pomme sip disable NAMEfirst. - Restore AMFI with
pomme amfi enable NAMEbefore you turn SIP on again. - See Change SIP and AMFI.
security-agent-unsupported
Section titled “security-agent-unsupported”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:
- Run
pomme agent update NAMEto install the current agent, then retry. - If the update isn’t possible, create a new VM with this version of Pomme.
security-agent-unverified
Section titled “security-agent-unverified”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:
- Run
pomme agent status NAMEto check the agent. - Run
pomme agent repair NAMEif the agent is missing or damaged, then retry.
security-auto-login-unavailable
Section titled “security-auto-login-unavailable”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:
- Turn off the setting that the message names in the guest, then repeat the same command.
- See Change SIP and AMFI.
security-change-unverified
Section titled “security-change-unverified”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI.
security-command-incomplete
Section titled “security-command-incomplete”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.
security-credential-conflict
Section titled “security-credential-conflict”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.
security-credential-invalid
Section titled “security-credential-invalid”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.
security-desktop-unverified
Section titled “security-desktop-unverified”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.
security-journal-damaged
Section titled “security-journal-damaged”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:
- Check that the VM bundle’s files are owned by your account and aren’t writable by others.
- Run
pomme bug-report NAMEand 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.
security-journal-write-failed
Section titled “security-journal-write-failed”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:
- Check that the volume that holds the VM has free space and is writable.
- Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI.
security-operation-pending
Section titled “security-operation-pending”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.
security-owner-account-conflict
Section titled “security-owner-account-conflict”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.
security-owner-login-unverified
Section titled “security-owner-login-unverified”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.
security-owner-not-fresh
Section titled “security-owner-not-fresh”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.
security-owner-preparation-failed
Section titled “security-owner-preparation-failed”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:
- Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI. - If it happens again, run
pomme bug-report NAMEand attach the file to a new issue.
security-owner-unverified
Section titled “security-owner-unverified”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:
- Check the user name and credential that you provided.
- See Change SIP and AMFI.
security-private-input-failed
Section titled “security-private-input-failed”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:
- Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI. - If it happens again, run
pomme bug-report NAMEand attach the file to a new issue.
security-reboot-unverified
Section titled “security-reboot-unverified”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:
- Run
pomme status NAMEto see the VM’s state. - Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI.
security-recovery-command-failed
Section titled “security-recovery-command-failed”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI.
security-request-mismatch
Section titled “security-request-mismatch”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.
security-restoration-incomplete
Section titled “security-restoration-incomplete”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:
- Run
pomme status NAMEto see the VM’s state. - Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI.
security-rollback-unverified
Section titled “security-rollback-unverified”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Repeat the same
pomme siporpomme amfiaction with the same--final-statevalue to resume. See Change SIP and AMFI. - If it happens again, run
pomme bug-report NAMEand 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.
security-state-conflict
Section titled “security-state-conflict”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Run
pomme bug-report NAMEand 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.
security-state-damaged
Section titled “security-state-damaged”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:
- Check that the VM bundle’s files are owned by your account and aren’t writable by others.
- Run
pomme bug-report NAMEand 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.
security-state-stale
Section titled “security-state-stale”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Run the SIP or AMFI command again to start a new operation.
security-state-write-failed
Section titled “security-state-write-failed”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.
security-status-unverified
Section titled “security-status-unverified”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Run
pomme agent status NAMEto check that the guest agent is connected.
Recovery
Section titled “Recovery”recovery-agent-failed
Section titled “recovery-agent-failed”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:
- Run
pomme status NAMEto see the VM’s state. - Stop the VM with
pomme stop NAME, then run the same command again. - Run the command with
--debugto save screenshots of each Recovery step.
recovery-authentication-failed
Section titled “recovery-authentication-failed”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:
- Run the same command again. Each attempt starts a new Recovery session.
- If the VM is slow to reach Recovery, stop other VMs to free memory and CPU, then retry.
recovery-cleanup-unverified
Section titled “recovery-cleanup-unverified”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:
- Run
pomme status NAMEto see the VM’s state. - Stop the VM with
pomme stop NAME, then run the same command again; Pomme cleans up the earlier session first.
recovery-final-state-unverified
Section titled “recovery-final-state-unverified”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:
- Run
pomme status NAMEto see the VM’s state. - Start or stop the VM yourself with
pomme start NAMEorpomme stop NAME.
recovery-launcher-rejected
Section titled “recovery-launcher-rejected”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:
- Reinstall Pomme with
pomme update, then run the command again. - If you built Pomme yourself, sign it with the same identity as the installed build.
recovery-operation-failed
Section titled “recovery-operation-failed”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:
- Run
pomme status NAMEto see the VM’s state. - Run the same command again. Each attempt starts a new Recovery session.
- If it happens again, run
pomme bug-report NAMEand 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-request-rejected
Section titled “recovery-request-rejected”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:
- Run the same command again. Each attempt starts a new Recovery session.
- If it happens again, run
pomme bug-report NAMEand 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-run-state-unavailable
Section titled “recovery-run-state-unavailable”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:
- Run
pomme status NAMEto see the VM’s state. - Run the command again after the VM finishes starting or stopping.
recovery-security-state-rejected
Section titled “recovery-security-state-rejected”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the VM’s security state. - Run
pomme bug-report NAMEand 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-session-invalid
Section titled “recovery-session-invalid”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:
- Stop the VM with
pomme stop NAME, then run the same command again. - Run
pomme bug-report NAMEand 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-staging-unsafe
Section titled “recovery-staging-unsafe”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:
- Check the ownership and permissions of the VM bundle with
ls -la. - Run Pomme as the user who created the VM, not with
sudo.
recovery-timed-out
Section titled “recovery-timed-out”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:
- Run
pomme status NAMEto see the VM’s state. - Stop the VM with
pomme stop NAME, then run the same command again. - Stop other VMs to free memory and CPU if the VM is slow.
recovery-workspace-unverified
Section titled “recovery-workspace-unverified”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:
- Stop the VM with
pomme stop NAME, then run the same command again. - If it happens again, run
pomme bug-report NAMEand 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.
mdm-agent-unverified
Section titled “mdm-agent-unverified”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:
- Run
pomme agent status NAMEto check the agent. - If the agent is out of date, run
pomme agent update NAME, then retrypomme mdm. - If the agent still lacks the MDM capabilities, recreate the VM with a current Pomme build. See Enroll in MDM.
mdm-cleanup-failed
Section titled “mdm-cleanup-failed”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.
mdm-downgrade-unsupported
Section titled “mdm-downgrade-unsupported”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.
mdm-enrollment-conflict
Section titled “mdm-enrollment-conflict”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:
- Supply the profile that the VM is enrolled with, or enroll a different VM.
- See Enroll in MDM.
mdm-enrollment-failed
Section titled “mdm-enrollment-failed”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:
- Run
pomme mdm NAME --profile PATH --debug --format jsonto see the failure stage and diagnostics. - Check that the guest can reach the MDM server, then retry
pomme mdmwith the same arguments.
mdm-enrollment-outcome-unknown
Section titled “mdm-enrollment-outcome-unknown”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:
- Retry
pomme mdmwith the same arguments. Pomme checks the guest’s enrollment before it does anything else. - Check the installed profiles in the guest’s System Settings > General > Device Management.
mdm-evidence-unavailable
Section titled “mdm-evidence-unavailable”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:
- Retry
pomme mdmwith the same arguments. - Check the installed profiles in the guest’s System Settings > General > Device Management.
mdm-helper-not-stopped
Section titled “mdm-helper-not-stopped”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:
- Check that no enrollment helper process is still running in the guest, for example with
pomme exec NAME -- /bin/ps -ax. - Retry
pomme mdmwith the same arguments to finish the enrollment.
mdm-journal-changed
Section titled “mdm-journal-changed”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.
mdm-journal-conflict
Section titled “mdm-journal-conflict”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.
mdm-journal-damaged
Section titled “mdm-journal-damaged”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:
- If you edited or copied the file, restore it.
- If the journal came from a newer Pomme build, install that build to finish the enrollment.
- Otherwise, run
pomme bug-report NAMEand attach the file to a new issue.
mdm-journal-state-invalid
Section titled “mdm-journal-state-invalid”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.
mdm-journal-write-failed
Section titled “mdm-journal-write-failed”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:
- Free space on the volume that holds your VMs if it’s full.
- Check the ownership and permissions of the VM bundle, then retry
pomme mdm.
mdm-operation-pending
Section titled “mdm-operation-pending”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:
- Repeat the original command with its original arguments to finish it.
- Then retry
pomme mdm.
mdm-preparation-incomplete
Section titled “mdm-preparation-incomplete”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:
- Run
pomme mdm NAME --profile PATH --dry-runto see the detected state. - Retry
pomme mdmwith the same arguments to resume.
mdm-profile-transfer-failed
Section titled “mdm-profile-transfer-failed”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:
- Run
pomme status NAMEto check that the VM and its guest agent are running. - Retry
pomme mdmwith the same arguments.
mdm-profile-unreadable
Section titled “mdm-profile-unreadable”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:
- Check that
--profilenames a regular.mobileconfigfile that you can read. - If the profile is a link, give the path of the file that it points to.
mdm-restoration-failed
Section titled “mdm-restoration-failed”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:
- Retry
pomme mdmwith the same arguments to resume restoration from its journal. - Run
pomme sip status NAMEandpomme amfi status NAMEto check the settings.
mdm-security-baseline-unavailable
Section titled “mdm-security-baseline-unavailable”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto check the settings. - Retry
pomme mdmwith the same arguments.
mdm-security-baseline-unsupported
Section titled “mdm-security-baseline-unsupported”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:
- Run
pomme sip status NAMEandpomme amfi status NAMEto see the current settings. - Set SIP and AMFI to a standard configuration with
pomme sipandpomme amfi, then retrypomme mdm. See Change SIP and AMFI.
mdm-staging-failed
Section titled “mdm-staging-failed”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:
- Retry
pomme mdmwith the same arguments. - If the failure continues, run
pomme agent repair NAME.
Display automation
Section titled “Display automation”display-frame-invalid
Section titled “display-frame-invalid”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:
- Wait for the VM to finish starting, then retry.
- If the error continues, run
pomme bug-reportand attach the file to a new issue.
display-frame-timeout
Section titled “display-frame-timeout”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:
- Wait for the VM to finish starting, then retry.
- Retry with a larger
--timeoutvalue.
display-geometry-unsupported
Section titled “display-geometry-unsupported”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:
- Run
pomme inspect NAMEto check the display configuration. - Create a new VM with
pomme create NAME, which uses the supported size.
display-input-interrupted
Section titled “display-input-interrupted”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:
- Take a screenshot with
pomme ui screenshotto check the VM’s screen. - Retry the command.
display-input-timeout
Section titled “display-input-timeout”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:
- Take a screenshot with
pomme ui screenshotto check the VM’s screen. - Retry with a larger
--timeoutvalue.
display-input-unavailable
Section titled “display-input-unavailable”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:
- Wait for the VM to finish starting, then retry.
- Restart the VM with
pomme restart NAME, then retry.
display-interface-mismatch
Section titled “display-interface-mismatch”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:
- Update Pomme with
pomme update, then retry. - If the error continues, run
pomme bug-reportand 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.
display-not-ready
Section titled “display-not-ready”The VM display isn’t ready yet.
Cause: The VM is still starting and hasn’t published its display or input devices.
Resolution:
- Wait for the VM to finish starting, then retry.
- Run
pomme status NAMEto check the VM’s state.
display-unavailable
Section titled “display-unavailable”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:
- Run
pomme status NAMEto check that the VM is running. - Restart the VM with
pomme restart NAME, then retry.
ui-debug-screenshot-failed
Section titled “ui-debug-screenshot-failed”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.
ui-recovery-cleanup-required
Section titled “ui-recovery-cleanup-required”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.
ui-recovery-input-unconfirmed
Section titled “ui-recovery-input-unconfirmed”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.
ui-recovery-no-input
Section titled “ui-recovery-no-input”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:
- Run the same command again.
- Run the same command again with
--debugto save a screenshot before each Recovery action.
ui-recovery-ownership-unverified
Section titled “ui-recovery-ownership-unverified”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:
- Run
pomme inspect NAMEto check the VM. - Stop the VM with
pomme stop NAME, then retry.
ui-recovery-profile-mismatch
Section titled “ui-recovery-profile-mismatch”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:
- Update Pomme with
pomme update. - Run
pomme bug-reportand 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.
ui-recovery-review-pending
Section titled “ui-recovery-review-pending”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:
- Create the VM from a supported macOS version. See Requirements.
- Update Pomme with
pomme updateto get newly supported builds.
ui-recovery-screen-unrecognized
Section titled “ui-recovery-screen-unrecognized”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:
- Run the same command again with
--debugto save a screenshot before each Recovery action. - See Recovery navigation stops.
ui-recovery-screen-unstable
Section titled “ui-recovery-screen-unstable”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:
- Run the same command again.
- Run the same command again with
--debugto save a screenshot before each Recovery action.
ui-recovery-sequence-invalid
Section titled “ui-recovery-sequence-invalid”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:
- Stop the VM with
pomme stop NAME, then run the same command again. - Run
pomme bug-reportand 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.
ui-recovery-terminal-unverified
Section titled “ui-recovery-terminal-unverified”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:
- Stop the VM with
pomme stop NAME, then run the same command again. - Run the same command again with
--debugto save a screenshot before each Recovery action.
ui-recovery-timed-out
Section titled “ui-recovery-timed-out”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:
- Run the same command again.
- Run the same command again with
--debugto save a screenshot before each Recovery action. - See Recovery navigation stops.
ui-recovery-unqualified
Section titled “ui-recovery-unqualified”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:
- Run
pomme inspect NAMEto check the VM’s macOS version. - See Recovery navigation stops.
ui-recovery-unsafe-command
Section titled “ui-recovery-unsafe-command”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.
ui-recovery-unsupported-build
Section titled “ui-recovery-unsupported-build”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.
ui-recovery-unsupported-locale
Section titled “ui-recovery-unsupported-locale”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.