Immutable. This exact content is served forever at /api/v1/blob/80132c0091511660.
--- name: mac-debug description: Diagnose a Mac automation that is failing, especially one failing silently. Use when a click does nothing, typing does not appear, the accessibility tree is empty, an AppleScript hangs or errors, coordinates land in the wrong place, or something that worked before stopped working. requires: [chewie] --- # 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 ```bash 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. ```bash 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. ```bash 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 | Code | Meaning | Fix | |------|---------|-----| | -1743 | Not authorized | `tccutil reset AppleEvents`, retry in the foreground | | -600 | App not running | `open -a "App"`, then poll until System Events sees it | | -1712 | Timeout (~2min) | `with timeout of 300 seconds`. Check for a blocking modal | | -1728 | Object does not exist | Not permissions. Read the app's dictionary | | -1750 | errOSASystemError | Usually TCC, reported uselessly | ### `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`.