claude-mods/skills/mac-ops/references/panic-codes.md

macOS Kernel Panic Codes

Load this when decoding a kernel panic report from /Library/Logs/DiagnosticReports/. macOS doesn't use numeric bugcheck codes the way Windows does — instead, panics carry strings. The string + the loaded kext list together identify the cause.

Contents

1. Panic file formats
2. Anatomy of a panic report
3. Common panic strings
4. Kext provenance — Apple vs third-party
5. Apple Silicon panic specifics
6. Pre-panic correlation
7. When there's no panic report

Panic file formats

Era	Path	Format
macOS 10.x → 11	/Library/Logs/DiagnosticReports/*.panic	Plain text
macOS 12+	/Library/Logs/DiagnosticReports/Kernel_*.ips	JSON header + plain-text body
User-mode crashes	~/Library/Logs/DiagnosticReports/*.ips	App crashes (not kernel panics)

.ips files have a JSON metadata header on the first line, then the panic body below. To extract the body:

tail -n +2 /Library/Logs/DiagnosticReports/Kernel-2026-05-15-031422.ips

Anatomy of a panic report

A typical panic report contains:

panic(cpu N caller 0x...): "<panic string>"@<source-file>:<line>
Backtrace (CPU N), Frame : Return Address
0xffffffaeb01: 0xffff80019c... addr2line: __ZN16IOPlatformPlugin...
...
Mac OS version: 23F79
Kernel version: Darwin Kernel Version 23.5.0...
Kernel UUID:    ABC...
iBoot version:  iBoot-10151.121.1
secure boot?:   YES
roots installed: 0
Paniclog version: 14

Loaded kexts:
  com.apple.driver.AppleEFIRuntime    1
  com.apple.iokit.IOACPIFamily        1.5
  com.example.product.kext            2.1.7      <— third-party suspect
  ...

The panic string identifies the failure class. The call stack points at the kext / function. The kext list narrows the suspect.

Common panic strings

Storage / IO

String fragment	Likely cause	First action
"Sleep wake failure in EFI"	Driver hung crossing sleep/wake	Check USB / BT / GPU driver versions; remove third-party kext
"unresponsive bootstrap subsystem"	launchd deadlock at boot	Boot safe mode; audit /Library/LaunchDaemons/
"VFS error mounting volume"	Filesystem mount failed	Boot recoveryOS, run diskutil verifyVolume
"APFS reaper: ... corruption"	APFS metadata corruption	Image first; do NOT fsck_apfs -y
"IOPlatformPanicAction"	Hardware-initiated panic (often thermal / power)	Check pmset -g log for power events around panic time

Memory / pagefault

Fragment	Cause
"Kernel trap at ... page_fault"	Kernel-mode memory access fault — driver bug or RAM fault
"double_fault"	Kernel handler itself crashed during fault handling — very serious
"general_protection"	Kernel touched invalid memory region
"Kernel data abort" (Apple Silicon)	Memory access violation in kernel/kext

Driver / kext

Fragment	Cause
"WindowServer panic" or "AGXFirmwareKernExt"	GPU driver fault. Try external display, alternative GPU mode
"Bluetooth panic" or "IOBluetoothFamily"	BT stack issue — unpair recent devices
"AppleACPIPlatform"	ACPI / firmware interaction — rare but tied to motherboard
"AppleAHCIPort" / "AppleNVMeFamily"	Storage controller. Check disk-health
"IOAudioFamily" / "AppleHDA"	Audio driver. Often triggered by external audio interface
"IOUSBHostFamily"	USB driver fault — unplug recent USB devices
"IOFireWireFamily"	FireWire (legacy) — rare on modern Macs

Sleep / power

Fragment	Cause
"Sleep wake failure"	Driver crossing power state. Look at backtrace for kext name
"Wake transition timed out"	Specific driver took too long to wake
"smc panic" (rare)	SMC firmware issue. Reset SMC (Intel only — Apple Silicon doesn't have user-resetable SMC)

Watchdog / hang

Fragment	Cause
"panic_kthread"	Kernel watchdog timeout — a driver was in infinite loop
"Hard hang on cpu N"	Specific CPU stuck — possibly hardware

Kext provenance — Apple vs third-party

The most important triage: is the panic in an Apple kext, or a third-party kext?

Prefix	Origin	Diagnostic value
com.apple.*	Apple-shipped	Harder to fix — likely a bug. Check for OS updates.
com.<vendor>.* (Adobe, Paragon, Eltima, ESET, etc.)	Third-party	Primary suspect. Try removing/updating the kext.

Common third-party kexts that show up in panics:

Kext label	Vendor	Reason
com.eltima.ProductX	Eltima Software	USB virtualization, often crashes
com.paragon-software.fs.kext.ntfs	Paragon NTFS	Filesystem driver
com.eset.kext.esets-eset_ctl	ESET	Anti-virus / firewall
com.kaspersky.kext.*	Kaspersky	AV
com.driver.AcmeUSB	Misc. drivers	Various
com.intel.driver.EnergyDriver	Intel (Boot Camp era)	Power management

If you see ANY com.<thirdparty> kext in the panic kext list, that's your starting point — especially if it appears in the call stack itself, not just the loaded-kext inventory.

Note: many vendors now ship System Extensions instead of kexts (especially on Apple Silicon). System extensions show up differently — see references/launchd-deep-dive.md.

Apple Silicon panic specifics

Apple Silicon panics use a slightly different format and include more hardware context. Key differences:

• Panic file naming: Kernel-YYYY-MM-DD-HHMMSS.panic and .ips
• Backtrace addresses are ARM64
• "secure boot?: YES" line at the bottom (vs Intel's variable response)
• Some panic strings differ — e.g. "Kernel data abort" (ARM64) vs "page_fault" (x86)
• Apple Silicon has no SMC-resettable; recoveryOS handles equivalent reset
• T2 chip references absent on Apple Silicon (T2 was Intel-era; Apple Silicon has equivalent in SoC)

Pre-panic correlation

The panic record is the symptom. The events in the 10 minutes before are usually the cause. Use:

# Replace TIME with the panic timestamp
log show --start '2026-05-15 03:04:22' --end '2026-05-15 03:14:22' --style compact \
    --predicate '(subsystem == "com.apple.kernel" OR subsystem == "com.apple.iokit") AND (messageType == "Error" OR messageType == "Fault")'

What to look for:

• storage: IOATAFamily / AppleNVMeFamily errors → IO error cascade
• driver hang: repeated identical kernel messages from a single kext
• assertion held: a process kept the system from sleeping → eventually hung during forced sleep
• silence: no events for >60s before panic → total system freeze (often hardware or kernel deadlock)

The scripts/panic-triage.sh script automates this window query.

When there's no panic report

Two common reasons:

1. Hard power loss — kernel didn't get to write the dump. Symptom: Mac restarts unexpectedly, nothing in /Library/Logs/DiagnosticReports/. Check pmset -g log for "Standby" → sudden "Wake" without preceding "Sleep".
2. Disk too full — kernel couldn't allocate space for the panic file. Free up space; ensure root volume has at least a few GB free.

For Apple Silicon: the system reset record (which IS preserved across hard power loss) is queryable via:

log show --predicate 'eventMessage CONTAINS "previous shutdown cause"' --last 30d | head

Negative values indicate unclean shutdown:

• -3 = hard power loss
• -20 = no associated cause / unexpected
• -128 = thermal shutdown
• 5 = clean shutdown initiated by user

Cross-references

• scripts/panic-triage.sh — automated panic decode + pre-panic timeline
• For storage-induced panics, see storage-events.md
• For Windows BugCheck equivalents, see windows-ops/references/bugcheck-codes.md
• For recovery from no-boot post-panic, see recovery-patterns.md