10. Troubleshooting

Start every investigation with the health check — it answers “what’s running and what isn’t” in a few seconds:

~/bin/health-check.sh

Then find your symptom below.

The Mac went to sleep anyway

• Run pmset -g and confirm sleep 0. If not, run setup-power.sh --apply.
• pmset -g log | grep -E "\b(Sleep|Wake)\b" | tail -n 20 shows when and why it slept.
• Check System Settings → Energy — a macOS update or a UPS being plugged in can surface different settings. Re-running setup-power.sh is harmless.

It didn’t come back after a power cut

It’s on, but nothing is reachable. It’s almost certainly waiting at the FileVault unlock screen.

• macOS 26+: from a device on the same LAN, ssh you@your-mac-mini.local and enter your password (details). Tailscale won’t work until after unlock.
• Earlier macOS: someone needs to type the password at the Mac.

It’s off.

• pmset -g | grep -w autorestart should show 1. (Without -w you also match autorestartatconnect, a separate setting that newer macOS lists first.) Some users report the setting not taking effect reliably on certain models and macOS versions; toggle it off and on in System Settings → Energy.
• If a UPS shut the Mac down cleanly, autorestart doesn’t apply. Add the daily power-on backstop: setup-power.sh --apply --daily-poweron 04:30.

Tailscale shows the Mac as offline

• Is anyone logged in? With FileVault on and no auto-login, the Tailscale app starts only after login.
• Key expiry: in the admin console, check whether the machine’s key expired; re-authenticate it and Disable key expiry.
• Run tailscale status on the Mac (via Screen Sharing on the LAN, or at the Mac). If you get command not found, the CLI integration isn’t installed; use /Applications/Tailscale.app/Contents/MacOS/Tailscale status instead.

Screen Sharing shows a black or tiny screen

• The Mac may be at the lock screen or the display may be asleep — click or press a key.
• Headless Macs sometimes pick an odd resolution. In a High Performance session, choose a resolution in the Screen Sharing toolbar; or use an HDMI dummy plug.

A LaunchAgent isn’t running

launchctl print gui/$(id -u)/com.example.ai-worker | grep -E "state|last exit code|last terminating signal|path"
tail -n 50 ~/Library/Logs/com.example.ai-worker/stderr.log
plutil -lint ~/Library/LaunchAgents/com.example.ai-worker.plist

Symptom	Likely cause	Fix
Could not find service	Not loaded	launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist
Bootstrap failed: 5: Input/output error	Already loaded, or the plist is invalid	bootout first; run plutil -lint
Last exit code 78	launchd couldn’t start it: bad path, missing working directory or log folder	Check every path is absolute and exists
Last exit code 127 / command not found in the log	The program isn’t on launchd’s PATH	Use absolute paths; set PATH in EnvironmentVariables
last terminating signal = Killed: 9 (no exit code)	It crashed or was killed, for example by macOS under memory pressure	Read stderr.log; check memory use
Operation not permitted in the log	macOS privacy protection	Privacy permissions
Starts, then restarts every ~30 s	It exits immediately; KeepAlive relaunches it	Read stderr.log; run the command by hand
Doesn’t start after a reboot	Nobody logged in, or it’s switched off under Allow in the Background	Log in; check Login Items & Extensions

The Cursor worker is offline

• launchctl print gui/$(id -u)/com.example.cursor-worker — is it running?
• agent --version, then agent update if it’s old.
• Sign-in expired? Run agent login once interactively (Screen Sharing if needed).
• The worker needs outbound HTTPS to Cursor’s servers; check any firewall, VPN or DNS filter on your network.

Claude Code or another CLI “isn’t found” in a job

Your shell’s PATH (from ~/.zprofile) isn’t used by launchd. Set PATH in the plist’s EnvironmentVariables to include ~/.local/bin and /opt/homebrew/bin — as absolute paths.

A cloud folder isn’t syncing

• Is the client running? health-check.sh --app "Google Drive" --app OneDrive.
• Open the client’s menu-bar icon — it usually says why (signed out, disk full, paused).
• Make sure the folders your agents use are set to keep downloaded (details).

The disk is filling up

df -h /System/Volumes/Data
du -sh ~/Library/Caches ~/Library/Developer ~/code/* 2>/dev/null | sort -h | tail
brew cleanup

Look at Avail, which is the free space for the whole disk. Don’t go by the Capacity column of df -h /: / is the read-only system volume, so it only counts the ~13 GB of macOS itself and can show single digits on a disk that’s nearly full. Finder can show a little more free space than df because it counts purgeable files (caches, local snapshots) as free.

Also check Docker images (docker system df), local model folders, and old Time Machine local snapshots (tmutil listlocalsnapshots /).

Handy commands

Command	What it tells you
pmset -g	Current power settings
pmset -g assertions	What is keeping the Mac awake
pmset -g sched	Scheduled power events
fdesetup status	FileVault on/off
sudo systemsetup -getremotelogin	SSH on/off
launchctl print gui/$(id -u)	Everything loaded in your session
log show --last 1h --predicate 'process == "launchd"'	Recent launchd messages
last reboot | head	Recent restarts
tailscale status	Tailnet connection and peers