Troubleshooting
Every failure on this page is one we hit ourselves building the thing. Most of them are not bugs, and all of them look like bugs the first time.
Everything returns empty and nothing errors
No windows, no elements, no matches - but the tools report success.
The cause is almost always a full-screen app. A full-screen window on macOS gets its own Space, and everything else lives on another one. Both the accessibility API and the screenshot see only the Space that is currently in front.
This one cost us an afternoon. Safari, Chrome, VS Code and a test window we had just created all reported zero windows, and it looked exactly like a broken lookup. Then the window server agreed: five windows on screen, all belonging to the full-screen editor.
Check it: call computer_windows with no filter. If every window belongs to one app, you are looking at that app's Space. Leave full screen, or use computer_activate to switch to the app you actually mean.
One app returns almost nothing, but others work
A handful of nodes, no buttons - while other apps return hundreds.
Different from the entry above: there, everything is empty. Here it is one app, and the cause is that app rather than your setup.
Chromium builds its accessibility tree lazily, and an Electron app can ship without ever enabling it. Measured on two Electron apps on the same machine at the same moment: one returned 2000 nodes and 80 buttons, the other returned 8 nodes and none - at depth 14, at depth 30 and at depth 60 alike. Raising the limit does not help, because there is nothing behind it.
Tell them apart: run computer_inspect on a second app. If that one is full, the first app is the one holding out. Fall back to screenshots and coordinates for it, accept that this is more brittle, and if you work out a reliable path, write it down as a recipe.
Permission denied, but you granted permission
"Accessibility access missing" even though the checkbox is on.
macOS grants these permissions to the application that runs the process, not to the package. That is your terminal, or your editor, or whatever launched the MCP client. Granting it to something else, or to a second terminal you no longer use, changes nothing.
Call computer_permissions first. It reports both permissions as booleans and names what to do. Then restart the host app: the permission is read at launch, so a running process keeps the answer it started with.
Zero secure fields found
Screenshots come back with redactedRegions: 0.
Usually correct: there was nothing sensitive on screen. But it is also what you see when the scan cannot see anything at all, which is the dangerous version of the same number.
Two ways to tell them apart. computer_inspect on the app with the field should return nodes marked "secure": true. And if computer_windows is also empty, read the first entry on this page.
A field that stays visible when it should not is a security bug here, not a feature request. There is an issue form for it. Describe the field rather than attaching the screenshot - the whole point is that the image holds something you did not want to share.
The click landed somewhere else entirely
The agent clicked a coordinate it read from a screenshot, and hit the wrong thing.
Pixels are not points. A Retina screenshot of a 1710-point-wide screen is 3420 pixels wide; scaled down with maxWidth it might be 1400. computer_click takes points. So a coordinate read straight off the image is wrong by the scale factor - at full resolution, by half the screen.
Every screenshot reply carries pixelsPerPoint along with the screen size in points. Divide the image coordinate by it before clicking. And where an accessibility element exists, use computer_find instead: frames come back in points already.
The keystrokes went somewhere else
Text appeared in the wrong app, or nowhere.
computer_type types into whatever has keyboard focus right now. It does not target an app, and it has no way to know what you meant. Activate the app, click or press the field, then type. And check afterwards: a screenshot costs 0.4 seconds and is cheaper than discovering it half an hour later.
The agent clicks the same thing over and over
The same action repeats and the screen does not change.
An agent working from a stale screenshot will keep acting on a screen that no longer exists. Take a fresh screenshot, or better, use computer_inspect, which tells you what is there now rather than what it looked like.
If an element cannot be found, that is information, not a reason to try again harder.
The helper cannot be found
"cmcp-helper was not found."
The server looks in three places in order: CMCP_HELPER if you set it, the binary shipped inside the package, then a locally built one. If all three miss:
cd computerMCP/helper
swift build -c releaseOr point at a binary you already have with CMCP_HELPER=/path/to/cmcp-helper.
The write tools are not listed
The agent can look but says it has no way to click.
CMCP_MODE=readonly does not list them at all, on purpose: a model that can see a tool will eventually try it, and a refusal per call is noise. Set the mode to ask and restart the client.
A dialog appeared and nothing happened
The action was refused with "said no or did not answer".
The consent dialog expires, and an expired dialog refuses. That is deliberate: a prompt that resolves to yes because nobody saw it is not consent.
If you are running headless or on a machine you are not sitting at, either stay in readonly or raise CMCP_ASK_TIMEOUT. Do not leave a session in a mode where it will ask questions nobody is there to answer.
Screenshots are slow
They should take around 0.4 seconds, most of which is the capture itself. If yours are much slower, check the machine's load first: we measured the same unchanged code at anything from 0.4 to 18 seconds while the system was busy, and wrongly blamed our own change for it. Measure with and without redaction back to back, so both see the same conditions.
Still stuck
Open an issue with the output of computer_permissions, the last few lines of computer_audit, and what you expected to happen. The audit log holds no credential text, so it is safe to paste.