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

To troubleshoot vPhone-CLI errors, match the Swift enum case from 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, 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, ROM loading in VPhoneAppDelegate.swift, and VM configuration in VPhoneVirtualMachine.swift.

Execution Flow and Validation Points

The tool validates components in strict sequence. First, VPhoneCLI.swift uses ArgumentParser to convert CLI options into a VPhoneVirtualMachine.Options struct. Next, VPhoneHardwareModel.swift verifies macOS 15+ compatibility and private entitlements. Finally, 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, 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 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, 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, 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), 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.

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.

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:

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:

./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:

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
• romNotFound indicates a missing IPSW-derived ROM image; use fw_prepare.sh to generate valid files for VPhoneAppDelegate.swift
• diskNotFound signals a missing writable image; run vm_create.sh to produce compatible disk files validated by 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 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}