# How to Force EXC_GUARD Patch on iOS 26.x Bases with vphone-cli

> Force EXC_GUARD patch on iOS 26.x bases with vphone-cli using the --force-exc-guard flag or FORCE_EXC_GUARD=1 for manual control.

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

---

**Use the `--force-exc-guard` CLI flag or set `FORCE_EXC_GUARD=1` to manually enable the Mach-port guard disable patch when working with iOS 26.x bases in vphone-cli.**

The `vphone-cli` tool automatically applies the `EXC_GUARD` disable patch for iOS 18 bases to prevent crash loops, but treats iOS 26.x as stable without this modification. When you need to force EXC_GUARD patch even on 26.x bases with vphone-cli, the repository provides explicit opt-in mechanisms through command-line arguments and environment variables.

## Why iOS 26.x Requires Explicit Opt-In for EXC_GUARD Patches

By default, `vphone-cli` only disables `EXC_GUARD` (specifically `GUARD_TYPE_MACH_PORT`) for iOS 18 bases where the kernel crash-loop makes the patch mandatory. The firmware pipeline evaluates whether to apply the guard-disable logic based on the iOS base version and an explicit override flag.

In [`sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift), the decision logic evaluates:

```swift
let applyExcGuard = iosBaseIs18 || forceExcGuard

```

When `iosBaseIs18` is false (as with 26.x bases) and `forceExcGuard` remains false, the system skips the `EXC_GUARD` patch to avoid unnecessary kernel modifications. This conservative approach prevents altering stable 26.x kernels unless explicitly requested.

## Force the Patch Using the CLI Flag

The most direct method to enable the patch for a single operation is the `--force-exc-guard` argument.

```bash
vphone-cli fw patch myphone --variant regular --force-exc-guard

```

After patching completes, you must restore or install the custom firmware (CFW) again so the device boots with the modified kernel image:

```bash
vphone-cli restore myphone

```

The flag definition resides in [`sources/vphone-cli/VPhoneFWCLI.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/vphone-cli/VPhoneFWCLI.swift), where the `@Flag` property wrapper exposes the `--force-exc-guard` option to the command interface.

## Alternative Activation Methods

### Using Environment Variables

You can export the `FORCE_EXC_GUARD` variable before executing any firmware patch command. This approach works across all `vphone-cli` subcommands without modifying the invocation syntax.

```bash
FORCE_EXC_GUARD=1 vphone-cli fw patch myphone --variant jb

```

### Using the Makefile Wrapper

For automated workflows or dev variants, the repository's Makefile automatically translates the `FORCE_EXC_GUARD` make variable into the CLI flag. Set it when invoking any `fw_patch*` target:

```bash
make fw_patch_dev VM=myphone FORCE_EXC_GUARD=1

```

The Makefile logic (around line 354) conditionally appends `--force-exc-guard` when the variable equals `1` or `true`:

```makefile
$(if $(filter 1 true yes,$(FORCE_EXC_GUARD)),--force-exc-guard,)

```

After Makefile-based patching, complete the installation with:

```bash
make cfw_install_dev VM=myphone

```

## How the Patch Applies to the Kernel

When `forceExcGuard` evaluates to true, the `KernelPatcher` class in [`sources/FirmwarePatcher/Kernel/KernelPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/sources/FirmwarePatcher/Kernel/KernelPatcher.swift) executes the guard-disable routine. The patcher checks the combined condition:

```swift
if isDev || applyExcGuard {
    patchExcGuardBehavior()
}

```

The `patchExcGuardBehavior()` method injects the necessary kernel modifications to disable `GUARD_TYPE_MACH_PORT` exceptions. This occurs during the firmware pipeline's kernel processing stage, ensuring the patched image contains the disabled guard behavior before serialization to disk.

## Summary

- **Default behavior**: `vphone-cli` automatically patches `EXC_GUARD` only for iOS 18 bases, leaving iOS 26.x untouched.
- **Force activation**: Use `--force-exc-guard` flag, `FORCE_EXC_GUARD=1` environment variable, or Makefile equivalent.
- **Source logic**: [`FirmwarePipeline.swift`](https://github.com/Lakr233/vphone-cli/blob/main/FirmwarePipeline.swift) controls eligibility via `applyExcGuard = iosBaseIs18 || forceExcGuard`.
- **Kernel modification**: [`KernelPatcher.swift`](https://github.com/Lakr233/vphone-cli/blob/main/KernelPatcher.swift) applies `patchExcGuardBehavior()` when the flag is enabled.
- **Deployment requirement**: Always re-patch and restore/reinstall the CFW after enabling the flag for changes to take effect.

## Frequently Asked Questions

### What is the EXC_GUARD patch and why disable it?

The `EXC_GUARD` patch disables Mach-port guard exceptions (`GUARD_TYPE_MACH_PORT`) in the iOS kernel. According to the source code, iOS 18 bases require this modification to prevent crash-loop behavior during boot, while iOS 26.x bases function correctly without it.

### Does forcing the patch on iOS 26.x cause instability?

The patch is opt-in for iOS 26.x because the base system does not require it for stability. While `vphone-cli` allows forcing the patch via `--force-exc-guard`, you should only enable it when troubleshooting specific Mach-port guard issues or following specialized workflows that explicitly require disabled guards.

### Why must I restore the device after patching?

The firmware patch command modifies the stored kernel image on disk. The running device continues using the previously cached kernel until you execute `vphone-cli restore` or install the CFW again, which flashes the newly patched image to the device and triggers a boot sequence with the modified `EXC_GUARD` behavior.

### Can I use the Makefile and CLI flag together?

Yes. If you set `FORCE_EXC_GUARD=1` while using the Makefile, it automatically appends `--force-exc-guard` to the underlying `vphone-cli` invocation. Setting the environment variable manually before a direct CLI command achieves the same result without the Makefile wrapper.