Debugging Mac automation

Most of these fail with no error, which is what makes them expensive. Diagnose before you retry, and never respond to a failure by escalating to a screenshot. A failing layer-3 read almost always means one specific fixable thing.

Triage

chewie doctor                    # grants, host app, tools
chewie doctor --secure-input     # is the keyboard being blocked

By symptom

Typing does nothing, no error

Secure Input. A password field has focus somewhere, and macOS discards synthetic keystrokes with no error. It is a process-global reference-counted flag, so one stuck app starves the whole system.

ioreg -l -w 0 -d 1 -k IOConsoleUsers | grep -o 'kCGSSessionSecureInputPID"=[0-9]*'

Nonzero is the pid holding it. Fix: open -a Finder, retry. If an app is stuck, focus and unfocus it, or quit it.

Clicks do nothing from inside an app

App Sandbox silently blocks CGEvent.post. No error. No fix inside the sandbox; this is why every serious macOS automation tool ships outside the App Store.

Accessibility tree is empty or all elements unnamed

Chromium builds it lazily. Chrome, Edge, VS Code, Slack, Discord, Notion, Figma, Spotify.

chewie see --app Slack --force-ax

Sets AXManualAccessibility, waits ~400ms, re-reads. The wait matters: an immediate re-read still looks empty.

If that returns kAXErrorAttributeUnsupported (-25208) on a non-Chromium app, the app genuinely has no tree and you are at layer 5.

Clicks land at double the offset

Retina. Screenshots are 2x device pixels; CGEvent takes screen points. Halve the coordinate, or stop using coordinates and use refs.

Clicks land on the wrong monitor

Multi-display origins go negative. Use CGGetActiveDisplayList geometry, do not assume 0,0.

Clicking a ref hits the wrong element

Stale ref. It was scoped to a snapshot from before the UI changed. Re-snapshot after any sheet, navigation, resize, or scroll.

AppleScript errors

defaults write had no effect

Apps cache preferences in memory and rewrite on quit. Write with the app closed, or restart it. killall cfprefsd if a read looks stale.

chat.db rows have NULL text

Bodies moved to attributedBody on Ventura and later. Decode the typed stream, or use mac_messages_mcp.

"database is locked"

Open read-only (file:...?mode=ro) or copy to /tmp first.

do JavaScript fails in Safari

Develop > Allow JavaScript from Apple Events is off by default. Enable the Develop menu in Safari > Settings > Advanced first.

The web task dies at a login page

A fresh Playwright browser has no profile. Attach to the user's running Chrome: open -a "Google Chrome" --args --remote-debugging-port=9222.

It worked yesterday

Almost always: the TCC prompt was dismissed once and never returns, or the host app changed (different terminal, an update that re-signed the binary). chewie doctor.

Inspecting an element by hand

When chewie click "Save" cannot find something, the element is probably not called what it looks like it is called. Apple's Accessibility Inspector (bundled with Xcode) shows the real role, title, and available actions.

The stop rule

Three failures on the same action: stop and report what you tried and what you saw. Do not loop, and do not switch layers to route around a diagnosis you have not made.

Full list with detectors: docs/WORKAROUNDS.md and data/failure-modes.json.