Files
runaway/docs/troubleshooting.md
ruihan c31836d9e7
CI / ShellCheck (push) Failing after 12s
CI / Bash Syntax Check (push) Successful in 13s
CI / Markdown Lint (push) Successful in 15s
chore: remove remaining upstream author and origin-repo references
2026-11-09 10:45:03 +08:00

5.7 KiB

layout, title
layout title
default Troubleshooting — runaway

Troubleshooting

Common Errors

"Not a known DirStatus"

Volume auto-detection failed.

[ERR] Not a known DirStatus

Fix:

  1. Run diskutil list to find your Data volume
  2. Mount it: diskutil mount /dev/diskXsY
  3. Re-run runaway

"Full bypass must run from Recovery mode"

[ERR] Full bypass must run from Recovery mode.

Cause: bypass creates admin users via dscl, which only works in Recovery. Fix: Boot to Recovery and try again. Or use suppress instead from a booted system.


"Needs sudo" errors

Various commands require root:

[ERR] Firewall needs sudo: sudo ./runaway firewall
[ERR] Heal needs sudo: sudo ./runaway heal
[ERR] Hardening needs sudo: sudo ./runaway harden
[ERR] Audit needs sudo: sudo ./runaway audit
[ERR] Check needs sudo: sudo ./runaway check

Fix: Prepend sudo to the command.


MDM comes back after reboot

The most common cause is user-level artifacts carried over by Migration Assistant.

Fix from Recovery:

sudo ./runaway suppress

Fix from booted system:

sudo ./runaway harden

If it keeps returning:

sudo ./runaway persist   # auto-heal on every boot
sudo ./runaway monitor   # watch for re-enrollment

macOS update re-enabled MDM

System updates restore enrollment daemons automatically.

Fix:

sudo ./runaway heal

If you ran persist before the update, this runs automatically on next boot.


"Profiles status" still shows enrollment

This is cosmetic. macOS stores profile state on the read-only SSV (System Sealed Volume).

Don't trust profiles status -v. Trust runaway status -d instead.


FileVault is enabled

Runaway detects FileVault and prompts for the recovery key or volume password.

Fix: If automatic unlock fails, unlock the volume manually in Disk Utility first:

  1. Go to Disk Utility in Recovery
  2. Select the Data volume
  3. File → Unlock → Enter password
  4. Re-run runaway

iCloud stops working after bypass

The basic /etc/hosts block includes albert.apple.com (iCloud activation) and gdmf.apple.com.

Fix: Use whitelist instead of the basic block:

sudo ./runaway whitelist

Or manually remove these two lines from /etc/hosts:

0.0.0.0 albert.apple.com
0.0.0.0 gdmf.apple.com

"Not a macOS Data volume"

[ERR] Not a macOS Data volume

Cause: The mounted volume doesn't have the expected structure.

Fix: Run diskutil list to find the correct Data volume (look for "Data" in the name or the 69414d41-... role). Mount the right one and retry.


Monitor won't start

Check:

  1. Is it already running? sudo ./runaway monitor-status
  2. Permissions: needs root
  3. Check logs: /var/log/runaway-monitor.log

Fix:

sudo ./runaway monitor-stop
sudo ./runaway monitor

Can't download files in Recovery

Recovery mode has no internet by default.

Fix:

  1. Use a USB drive with runaway copied to it
  2. Or connect to Wi-Fi in Recovery (top-right menu → Wi-Fi icon)

"Library not found" error on startup

ERROR: Library not found: /path/to/lib/colors.sh

Cause: Running the source runaway script from outside the repo directory.

Fix:

  • Use the standalone version (runaway-standalone.sh) instead
  • Or run from the repo root where the lib/ directory exists

Firewall rules not applying

pf might have existing rules that conflict.

Fix:

sudo ./runaway firewall-off   # clear existing rules
sudo ./runaway firewall       # re-apply

"Device still locks after DFU restore"

A full DFU/IPSW restore doesn't remove ABM assignment — the serial stays in Apple Business Manager.

Strategy:

  1. After restore, do not connect to Wi-Fi
  2. Boot to Recovery
  3. Run runaway bypass before the device ever phones home
  4. Run runaway persist and runaway whitelist
  5. Only then connect to the internet

The serial stays in ABM forever — but if the device never connects without protections, it won't re-enroll.


GPG signature verification fails on update

[ERR] GPG signature verification failed

Fix:

  1. Make sure you have gpg installed
  2. Import the signing key: gpg --keyserver keys.openpgp.org --recv-key <KEY_ID>
  3. Try sudo ./runaway update again
  4. Or download manually from Releases

Logging

All commands produce structured logs:

[INF] Data volume: /Volumes/Macintosh HD - Data
[ OK] Admin 'apple' created (UID 501)
[WRN] DEP activation record present
[ERR] Firewall needs sudo: sudo ./runaway firewall
[STP] Locating Data volume by APFS role...
[DBG] Checking pfctl availability

Log format:

Prefix Level
[INF] Info — normal operation
[ OK] Success — operation completed
[WRN] Warning — non-critical issue
[ERR] Error — operation failed
[STP] Step — current action
[DBG] Debug — verbose only

Use --verbose for debug messages and --log-file <path> to save to a file:

sudo ./runaway heal --verbose --log-file /tmp/runaway.log

Diagnostic Commands

Run these to gather information before seeking help:

# Quick health check
sudo ./runaway doctor

# Full system audit
sudo ./runaway audit

# Generate report
sudo ./runaway report

# Dry-run a bypass
sudo ./runaway demo

Getting Help