# How to Troubleshoot vPhone-CLI Errors: A Complete Diagnostic Guide

> Troubleshoot vphone-cli errors effectively. Match Swift enum cases to failure modes like missing ROMs or invalid ports and apply targeted fixes for macOS issues. Resolve common vphone-cli problems now.

- Repository: [Lakr/vphone-cli](https://github.com/Lakr233/vphone-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To troubleshoot vPhone-CLI errors, match the Swift enum case from [`VPhoneError.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneError.swift) to four primary failure modes—hardware model validation failures, missing ROM images, missing disk images, or invalid kernel debug ports—and apply targeted fixes for macOS version requirements, code signing entitlements, or file system permissions.**

vPhone-CLI is a pure-Swift command-line tool that launches virtual iPhones using Apple’s Virtualization.framework. When the VM fails to initialize, the tool emits structured error messages defined in the `VPhoneError` enum, allowing you to troubleshoot vphone-cli errors by tracing each failure back to its specific validation point in the source code.

## Understanding the Error Architecture

### The VPhoneError Enum Definition

All runtime failures in vPhone-CLI originate from [`VPhoneError.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneError.swift), which defines the error contract used across the codebase. This central enum is thrown from three primary validation layers: hardware capability checks in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift), ROM loading in [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift), and VM configuration in [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift).

### Execution Flow and Validation Points

The tool validates components in strict sequence. First, [`VPhoneCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneCLI.swift) uses `ArgumentParser` to convert CLI options into a `VPhoneVirtualMachine.Options` struct. Next, [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) verifies macOS 15+ compatibility and private entitlements. Finally, [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) assembles the `VZVirtualMachineConfiguration` while validating disk images and debug ports before the VM starts.

## Resolving Specific vPhone-CLI Error Cases

### hardwareModelNotSupported

Thrown at line 32 of [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift), this error indicates the host system lacks required virtualization capabilities. The tool requires macOS 15 Sequoia or later, specific code signing entitlements, and disabled System Integrity Protection (SIP).

To resolve this error:

- Upgrade to macOS 15 Sequoia or later
- Verify the binary is signed with `com.apple.private.virtualization` and `com.apple.private.virtualization.security-research` entitlements using `codesign -dvvv <binary>`
- Disable SIP and AMFI by booting into Recovery mode and executing `csrutil disable`

### romNotFound(_: String)

This error originates at line 52 of [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift) when the `--rom` argument points to a non-existent iOS ROM image. The tool cannot locate the decrypted IPSW kernel and filesystem required for boot.

To fix this:

- Run `vphone-cli fw_prepare.sh` (or the `fw_prepare` Makefile target) to download and merge the required IPSW components
- Confirm the file exists: `ls -la <path>`
- Pass the absolute path to the `--rom` flag to avoid relative path resolution issues

### diskNotFound(_: String)

Thrown at lines 180-183 of [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), this indicates the writable disk image specified via `--disk` is missing or inaccessible. The VM requires a mutable disk image for iOS userdata persistence.

Resolution steps:

- Create a fresh VM directory using `./scripts/vm_create.sh <name>`, which generates `Disk.img`
- Verify file permissions: `test -f <path> && test -r <path> && test -w <path>`
- Ensure the CLI runs without sandbox restrictions that might block file I/O

### invalidKernelDebugPort(_: Int)

Encountered at lines 262-265 of [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift), this error occurs when the `--kernel-debug-port` value falls outside the valid range of 6000-65535. This port is used for connecting LLDB to the virtualized iOS kernel.

Solutions:

- Omit the `--kernel-debug-port` flag entirely to let the tool auto-select an available port
- Choose a port within the 6000-65535 range
- Verify the port is not already bound: `lsof -i :<port>`

## Step-by-Step Troubleshooting Workflow

When diagnosing failures, follow this systematic approach to isolate the root cause:

1. **Enable verbose logging**: Run all commands with the `-v` flag to activate `VPhoneVerbosity` (defined in [`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift)), which prints detailed execution steps including the exact validation point that fails.

2. **Analyze the error signature**: Swift errors display the enum case name in the stack trace. Match this against the `VPhoneError` definitions to identify whether the failure occurred during hardware checks, ROM loading, or VM configuration.

3. **Validate host environment**: Execute `system_profiler SPSoftwareDataType` to confirm macOS version 15+, and run `codesign -dvvv <binary>` to verify the presence of `com.apple.private.virtualization` entitlements required by [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift).

4. **Inspect file system assets**: Both ROM and Disk images are standard files. Use `stat <path>` to verify existence, size, and permissions. The ROM should be a valid `.im4p` or IPSW-derived image, while the disk should be a writable raw image created by [`vm_create.sh`](https://github.com/Lakr233/vphone-cli/blob/main/vm_create.sh).

5. **Review runtime logs**: After the VM starts, monitor console output for messages prefixed with `[vphone]`. For jailbreak variants, check `/var/log/vphone_jb_setup.log` for early-boot panics or setup failures.

## Practical Examples

Launch a VM with explicit paths and verbose output to identify where initialization fails:

```bash
vphone-cli \
  --rom /path/to/ROM.im4p \
  --disk /path/to/Disk.img \
  -v

```

Create a new VM directory with a fresh disk image, then launch:

```bash
./scripts/vm_create.sh MyPhone
vphone-cli \
  --rom ./MyPhone/ROM.im4p \
  --disk ./MyPhone/Disk.img

```

Avoid kernel debug port conflicts by disabling the debug stub:

```bash
vphone-cli \
  --no-kernel-debug \
  --rom ./ROM.im4p \
  --disk ./Disk.img

```

## Summary

- **hardwareModelNotSupported** requires macOS 15+, proper code signing entitlements, and disabled SIP/AMFI as enforced by [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift)
- **romNotFound** indicates a missing IPSW-derived ROM image; use [`fw_prepare.sh`](https://github.com/Lakr233/vphone-cli/blob/main/fw_prepare.sh) to generate valid files for [`VPhoneAppDelegate.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneAppDelegate.swift)
- **diskNotFound** signals a missing writable image; run [`vm_create.sh`](https://github.com/Lakr233/vphone-cli/blob/main/vm_create.sh) to produce compatible disk files validated by [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) lines 180-183
- **invalidKernelDebugPort** occurs when specifying ports outside 6000-65535; use the auto-selection feature or verify port availability
- Verbose mode (`-v`) leverages [`VPhoneVerbosity.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVerbosity.swift) to expose the exact validation layer that throws the error

## Frequently Asked Questions

### Why does vPhone-CLI require disabling SIP and AMFI?

Apple’s Virtualization.framework private APIs, accessed via the `com.apple.private.virtualization` entitlements checked in [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift), require unrestricted access to hardware virtualization features that SIP and AMFI normally block. Without disabling these security features in Recovery mode using `csrutil disable`, the hardware validation at line 32 of [`VPhoneHardwareModel.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneHardwareModel.swift) will always throw `hardwareModelNotSupported`.

### How do I verify my vPhone-CLI binary has the correct entitlements?

Run `codesign -dvvv /path/to/vphone-cli` and examine the output for `com.apple.private.virtualization` and `com.apple.private.virtualization.security-research` in the entitlements section. These entitlements are applied during the build process defined in the `Makefile`. If missing, rebuild using the `make` command which executes the proper signing scripts.

### Can I use a custom kernel debug port outside the 6000-65535 range?

No. The validation logic at lines 262-265 of [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift) explicitly checks that the port falls within 6000-65535. Attempting to use ports outside this range triggers `invalidKernelDebugPort`. Either omit the `--kernel-debug-port` flag to enable automatic port selection, or choose a value within the enforced bounds and verify availability with `lsof`.

### What is the fastest way to recreate a corrupted disk image?

Execute `./scripts/vm_create.sh <vm_name>` from the repository root. This script generates a fresh `Disk.img` in a new directory, replacing corrupted or incompatible disk images. After creation, reference the new image in your `vphone-cli` command using `--disk ./<vm_name>/Disk.img` to satisfy the check at lines 180-183 of [`VPhoneVirtualMachine.swift`](https://github.com/Lakr233/vphone-cli/blob/main/VPhoneVirtualMachine.swift).