Troubleshooting

Troubleshooting

Most problems are one of: not running with privileges, no backend available, Secure Boot blocking PCI access, or an argument the CPU doesn't support. Start with:

# Linux
sudo zenmaster --info
# Windows (Administrator)
zenmaster --info
# macOS
sudo python3 -m zenmaster --info

If --info shows a Backend: other than not initialized, the SMU is reachable and the problem is elsewhere (usually the argument). If it says not initialized, the problem is the backend: see below.

---

"root/admin privileges required"

SMU writes, --table, and --dump-table need elevation.

• Linux: run with sudo. If sudo zenmaster reports command not found, your install is in a user environment that sudo doesn't see on PATH. Use sudo python3 -m zenmaster ... or install system-wide with sudo pip install zenmaster.
• Windows: open the terminal as Administrator (right-click, Run as administrator), not a normal one.
• macOS: same "command not found" issue as Linux, and the same fix: sudo python3 -m zenmaster ... instead of sudo zenmaster ....

---

Linux: "PCI direct access is not available" / "not writable"

With Secure Boot off, ZenMaster always uses PCI direct access. If it can't:

1. Confirm you're running as root.
2. Check kernel lockdown is off (it can block PCI config writes even without Secure Boot).
3. If the PCI config space genuinely isn't there, your chipset path may differ from the expected 0000:00:00.0; open an issue with your --info output.

A loaded ryzen_smu module is not used when Secure Boot is off. The selection is by Secure Boot state, not by what's loaded.

---

Linux: Secure Boot is enabled

When Secure Boot is on, kernel lockdown blocks raw PCI access, and there is no fallback: you must use the ryzen_smu module. ZenMaster detects this and says so.

Options:

1. Use ryzen_smu. Build and install it, then sign the module with a MOK key and enroll it so it loads under Secure Boot:

   git clone https://github.com/amkillam/ryzen_smu
   cd ryzen_smu && make && sudo make install
   sudo modprobe ryzen_smu

2. Disable Secure Boot in UEFI firmware settings.

---

Linux: "ryzen_smu X is too old, upgrade to >= 0.1.7"

ZenMaster reads the module's drv_version and needs 0.1.7 or newer (it uses the /smn interface added in that release). Update the module:

cd ryzen_smu && git pull && make && sudo make install
sudo rmmod ryzen_smu && sudo modprobe ryzen_smu

---

Windows: "PawnIO driver is not installed"

Install PawnIO and reboot:

https://github.com/namazso/PawnIO.Setup/releases/latest/download/PawnIO_setup.exe

---

Windows: "PawnIO device not found" or "LoadBinary failed"

• The driver may need a reboot to activate after install.
• Make sure the terminal is elevated (Administrator).
• If you get error 1 (INVALID_FUNCTION), reinstall PawnIO from the link above.

---

macOS: "No SMU access path is available"

Neither DirectHW.kext nor the kext-free IOPCIBridge path is usable. The error message tells you exactly what's missing, but the two fixes are:

1. Install and load DirectHW.kext (this gets you --table/--sensors too): https://github.com/joevt/directhw. On a Hackintosh, SIP also needs to allow unsigned kexts, csr-active-config set to 03080000 in your OpenCore/Clover config.
2. Use the kext-free path: run as root and add the debug=0x144 boot-arg, then pass --iopci. This gets you tuning only, not the PM table.

---

macOS: "The IOPCIBridge path requires the debug=0x144 boot-arg"

You forced --iopci (or DirectHW isn't loaded, so ZenMaster fell back to it) without that boot-arg set. Add debug=0x144 to your bootloader config and reboot. There's no way around this requirement; it's how Apple's own IOPCIDiagnostics client gates config-space writes.

---

macOS: --table/--sensors say the PM table isn't available, but tuning works

You're on the kext-free IOPCIBridge path. It only reaches config space, not physical memory, so it can apply tuning arguments but can't read the PM table at all. Install DirectHW.kext if you want sensors too.

---

An argument is rejected

If a tuning line ends in something other than OK:

Status	Meaning	What to do
Rejected (prerequisite)	The SMU needs another state first (e.g. OC mode enabled)	Enable the prerequisite first, e.g. --enable-oc before OC clocks
Rejected (busy)	The mailbox was busy	Retry; avoid hammering the SMU from multiple tools at once
Unknown command	That opcode isn't valid on this firmware	The arg may not truly apply to your CPU
Failed	Generic failure	Check the value is sane for that field

Also check the value's unit and range: power is in mW (15000 = 15 W), current in mA, temperature in °C. A value far out of range is commonly rejected. See Tuning Arguments.

---

"not supported on " / help screen appears instead of running

The argument isn't in your CPU's command table, or a value argument was passed without =value. Run zenmaster --help to see exactly which arguments your CPU supports. The help list is authoritative: it's generated from your detected family.

---

--table says the PM table is unavailable

Not all families have a PM table (it's mostly APUs/mobile). If your family isn't covered, --table and --dump-table won't work and aren't shown in --help. See the supported list in PM Table and Monitoring.

On Linux PCI direct, the table is read over /dev/mem; if your kernel has CONFIG_STRICT_DEVMEM enabled it may block that region, in which case load the ryzen_smu module instead, which reads the table through sysfs. On macOS, the table needs DirectHW.kext specifically; the kext-free --iopci path can't read it at all.

---

Settings don't stick / get reset

Some firmware and vendor software periodically reset SMU limits. Use the reapply loop to hold them:

sudo zenmaster --stapm-limit=15000 --reapply=15

It re-applies every N seconds until you stop it with Ctrl-C. For persistence across reboots, wrap it in a systemd service (Linux) or a scheduled task at logon (Windows).

---

System becomes unstable or hard-locks

You set a value the silicon can't sustain (too aggressive an undervolt, too high a clock, too low a current limit). ZenMaster's writes are not persistent: reboot and the SMU returns to firmware defaults. Reboot, then dial the value back and test incrementally.

---

Still stuck

Open an issue with your zenmaster --info --json output and the exact command you ran: https://github.com/HorizonUnix/ZenMaster/issues