macOS accessibility automation: the four production failure modes nobody writes about

The naive version Apple shows you

If you read the AXUIElement reference and the WWDC session on accessibility, this is the version of the code you walk away with. It works in the happy path. It is wrong every other day in production, and the wrong-ness is silent: the function returns, your tool acts as if everything is fine, but no actual click was registered against the target app. The pattern below is what you'll see in 80% of the public sample code, including the Apple developer forums, the Stack Overflow answers, and the Swift packages in GitHub's top results.

// What every Apple sample shows you.
// Works in the happy path. Wrong every other day.

if AXIsProcessTrusted() {
    let app = AXUIElementCreateApplication(pid)
    var window: CFTypeRef?
    AXUIElementCopyAttributeValue(
        app, kAXFocusedWindowAttribute as CFString, &window
    )
    walk(window)
}

// Failure modes this never handles:
// 1. AXIsProcessTrusted lies after macOS auto-update.
// 2. cannotComplete on the focused app, but it just means
//    that app has no AX tree, not that we lost permission.
// 3. apiDisabled when system-wide AX is off in System Settings.
// 4. The user revoked permission mid-session and the cache
//    has not caught up yet.

Failure mode 1: stale TCC cache after a macOS update

The first time accessibility automation breaks for one of your users in production, this is what happened. They updated macOS overnight (or your app re-signed during an auto-update via Sparkle), they relaunched, the System Settings toggle still shows your app under Accessibility, and AXIsProcessTrusted() returns true. But every actual call to AXUIElementCopyAttributeValue comes back with kAXErrorAPIDisabled or kAXErrorCannotComplete. Your agent looks alive but does nothing. This was filed against macOS Sequoia in 2025 and it is still present in macOS 26 (Tahoe) in 2026.

The cause is that AXIsProcessTrusted reads from a per-process cache populated at first call. When TCC re-validates code signatures across an OS update, it can roll the live database forward without invalidating in-process caches in already-running processes. There is no notification API for this. Apple has not publicly acknowledged the cache as a bug; they have shipped documentation that implies AXIsProcessTrusted is the canonical check.

The recovery is to also probe the live database. The cheapest call that actually consults the live TCC state is CGEvent.tapCreate with .listenOnly options. Tap creation requires the same permission as the accessibility API (because event taps see synthetic input from other processes), and the result is not cached the same way. If the tap creates, you have the permission live; if it does not, you genuinely lost it. Invalidate the tap immediately so it does not eat events.

// AppState.swift, lines 307-371 (abridged).
// Two checks every poll cycle, not one.
// AXIsProcessTrusted alone returns stale data after macOS updates
// because the result is cached inside this process. We ALSO probe
// the live TCC database via CGEvent.tapCreate, which cannot be
// answered from a stale cache.

func checkAccessibilityPermission() {
    let tccGranted = AXIsProcessTrusted()
    let previouslyGranted = hasAccessibilityPermission

    if tccGranted {
        // AXIsProcessTrusted said yes, confirm by walking the front
        // app's window. cannotComplete or apiDisabled means the
        // cache is stale despite the TCC pane still showing granted.
        let broken = !testAccessibilityPermission()
        if broken { startAccessibilityRetryTimer() }
    } else if previouslyGranted && probeAccessibilityViaEventTap() {
        // AXIsProcessTrusted said no but live TCC says yes via the
        // event tap probe. Trust the live signal.
        log("ACCESSIBILITY_CHECK: stale cache detected")
    }
}

private func probeAccessibilityViaEventTap() -> Bool {
    let tap = CGEvent.tapCreate(
        tap: .cgSessionEventTap,
        place: .tailAppendEventTap,
        options: .listenOnly,
        eventsOfInterest: CGEventMask(1 << CGEventType.mouseMoved.rawValue),
        callback: { _, _, event, _ in Unmanaged.passRetained(event) },
        userInfo: nil
    )
    if let tap = tap {
        CFMachPortInvalidate(tap)
        return true
    }
    return false
}

Source: Desktop/Sources/AppState.swift, lines 307-371 and 487-504 in the Fazm repo. The full file in production handles three more edge cases: explicit transition logging when permission moves from granted to revoked or back, a Finder fallback for ambiguous errors (next section), and a retry timer that escalates to a restart prompt after three failed probes.

Failure mode 2: the kAXErrorCannotComplete trichotomy

You call AXUIElementCopyAttributeValue, you get back kAXErrorCannotComplete (raw value -25204). What does it mean?

One error code, three causes. If you treat them all the same way, you will either spam the user with permission alerts when they launch a Qt app, or silently fail when their permission is actually broken. The remediation is a simple cross-check: re-run the call against Finder.app, which is guaranteed to expose a full accessibility tree. Finder has shipped an AX implementation since 10.2 and Apple maintains it as part of every release.

The third cause: the agent process holds an AX handle to a target app that has since quit or been replaced (for example, Slack relaunching during an update). The handle goes stale and you get cannotComplete on every attribute read against that handle. This one is rarer and you handle it by always re-creating the AXUIElement from the current pid before walking, never caching the handle across event-loop ticks.

The Finder cross-check in source:

// AppState.swift, lines 465-485.
// kAXErrorCannotComplete is ambiguous: either we lost permission,
// OR the front app does not implement AX (Qt apps, OpenGL canvases,
// Python apps like PyMOL). Disambiguate by re-running the same call
// against Finder, which is guaranteed to expose a tree.

private func confirmAccessibilityBrokenViaFinder(suspectApp: String) -> Bool {
    if let finder = NSRunningApplication.runningApplications(
        withBundleIdentifier: "com.apple.finder").first {
        let finderElement = AXUIElementCreateApplication(finder.processIdentifier)
        var finderWindow: CFTypeRef?
        let finderResult = AXUIElementCopyAttributeValue(
            finderElement,
            kAXFocusedWindowAttribute as CFString,
            &finderWindow
        )
        if finderResult == .cannotComplete || finderResult == .apiDisabled {
            // Both apps fail. Permission is truly broken.
            log("AX broken confirmed by Finder (app: \(suspectApp))")
            return false
        } else {
            // Finder works, suspect app does not. App-specific gap.
            log("App \(suspectApp) has no AX; permission is fine")
            return true
        }
    }
    // Finder not running, fall back to event tap probe as tie-breaker.
    return probeAccessibilityViaEventTap()
}

The known-AX-empty apps in 2026, in approximate order of how often they trip this code path: PyMOL (Python + Qt), Wireshark (Qt), Telegram desktop pre-5.0 (Qt), Inkscape (GTK via XQuartz), Blender (OpenGL canvas), most Steam games, custom Metal renderers like the Arc Browser onboarding, scientific Python apps using matplotlib standalone windows, and old Tk apps. Native AppKit and SwiftUI apps almost never end up here unless the developer explicitly opted out via isAccessibilityElement = false on every view.

Failure mode 3: kAXErrorAPIDisabled

This one is unambiguous and rare: the user has system-wide accessibility turned off. There is no per-app toggle, just a single global state in TCC. The error code is -25211. Surface it immediately with a deep link to System Settings; do not retry, do not cross-check, do not wait for the cache to clear. The user is looking at the wrong UI and the only fix is a click in the right pane.

The deep link URL changed in macOS 13. Use x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility on Ventura and newer; on Monterey and older, the legacy URL was x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility (yes, identical string; the path Apple resolves changed internally). Open it via NSWorkspace.shared.open(URL) rather than open(1) so the activation comes from your app and macOS focuses the settings window correctly.

Logging note: the apiDisabled state can be surfaced repeatedly if your tool polls accessibility on a timer. Fazm logs apiDisabled exactly once per transition (lastAccessibilityApiDisabledLogged flag at AppState.swift line 449) to keep the support log readable. A noisy log that re-prints the same warning every poll cycle hides the actual signal.

Failure mode 4: the cache desyncs and you cannot fix it from inside the process

This is the punchline. If your agent ends up in the stale-cache state from failure mode 1, there is no public API to invalidate the cache. Apple does not expose AXResetTrustedCache(). The only working fix is to quit and relaunch the process. Every accessibility-based agent on macOS hits this and every one of them has to handle it the same way: detect it, retry a few times to confirm it is real, then ask the user to restart.

Fazm's pattern is three retries spaced 5 seconds apart, then a modal alert with two buttons: Quit & Reopen, or Later. The retry interval is 5 seconds because shorter intervals do not give TCC time to settle if the desync happened during an OS-level relaunch event, and longer intervals make the user feel like the app is hung. Three retries because the false-positive rate on a single failed test is real (a transient app launch can return cannotComplete during the first 200 ms of the process), but a three-in-a-row failure across 15 seconds is essentially never transient.

What this looks like in the logs of a healthy agent

One useful sanity check when you adopt the pattern above: the log stream from a healthy agent on macOS 26 looks like this on a poll cycle. Every line maps to a function in AppState.swift, and the ratio of lines you see in production tells you which failure mode your users are hitting most.

That last line, Permission confirmed via event tap probe, is the one that catches the stale-cache case. If you see it frequently, the user updated macOS recently. If you see the Quit & Reopen alert fire, the cache desync was real and the retry loop did not save it.

The full AXError vocabulary, mapped to actions

AXError has 13 cases in the public header. Most production code treats them as a binary success/fail, which is why most production code spams users with bogus permission alerts. The right handling is to split them by what they actually mean for an automation tool:

The remaining five (.invalidUIElementObserver, .cannotObserveUIElementNotifications, .notificationUnsupported, .notificationAlreadyRegistered, .notificationNotRegistered) only appear if you use the AXObserver notification API, which most automation tools do not. Fazm polls instead because the notification API has historically had its own set of bugs around process restart.

What this means if you're evaluating a tool, not building one

If you arrived here from a forum thread asking which macOS accessibility automation tool to use, the practical takeaway is this: the failure modes above are not optional. Every credible tool either handles them or quietly does not work for some of its users. Two questions to ask before you trust an agent on your machine:

1. Is the tool open source? If yes, grep for AXIsProcessTrusted and check whether the same file also calls CGEvent.tapCreate for the live probe. If only the first appears, the tool will silently break for users on macOS 15 or 26 after an OS update.
2. Does it expose a screenshot fallback? If the tool relies on accessibility for everything, it will be useless against your Qt and OpenGL apps. The right architecture is AX-first with a vision-based fallback that only fires when the AX tree is empty. Fazm exposes capture_screenshot as that fallback and the system prompt steers Claude to try macos-use tools first.

More on macOS accessibility automation

Frequently asked questions