Troubleshooting

Platform setup issues

Windows

"Could not find csc.exe"

CUP's TypeScript SDK compiles a small C# helper for UIA tree capture. This requires .NET Framework 4.x.

• .NET Framework is pre-installed on Windows 10/11. If missing, download from Microsoft.
• Verify: run where csc.exe in a terminal. It should be at C:\Windows\Microsoft.NET\Framework64\v4.x.x\csc.exe.

Empty tree or missing elements

• Some UWP/WinUI apps expose limited UIA trees. Try switching to detail="full" to see unpruned nodes.
• Elevated (Run as Administrator) windows may not expose their tree to non-elevated processes. Run your script as Administrator.

macOS

"Screen Recording permission is required"

CUP uses the accessibility API, which requires explicit permission on macOS.

1. Open System Settings > Privacy & Security > Accessibility
2. Add your terminal app (Terminal, iTerm2, VS Code, etc.)
3. For screenshots, also grant Screen Recording permission
4. Restart your terminal app after granting permissions

"No foreground window found"

• macOS can report no foreground window if the active app has no windows (e.g., Finder with no open windows).
• Try clicking on an app window before running snapshot().

Linux

"AT-SPI2 accessibility bus not available"

AT-SPI2 is the accessibility framework on Linux. It must be enabled:

# Check if AT-SPI2 is running
gdbus call --session --dest org.a11y.Bus --object-path /org/a11y/bus \
  --method org.a11y.Bus.GetAddress

# Enable AT-SPI2
export ACCESSIBILITY_ENABLED=1

# On GNOME, enable via gsettings
gsettings set org.gnome.desktop.interface toolkit-accessibility true

"libX11 not found" or "libXtst not found"

Install the required X11 libraries:

# Debian/Ubuntu
sudo apt install libx11-dev libxtst-dev

# Fedora
sudo dnf install libX11-devel libXtst-devel

# Arch
sudo pacman -S libx11 libxtst

"gdbus not found"

# Debian/Ubuntu
sudo apt install libglib2.0-bin

# Fedora
sudo dnf install glib2

Web (Chrome DevTools Protocol)

"Cannot connect to CDP"

Chrome must be launched with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

"No page targets"

CDP is connected but no tabs are visible. Open at least one tab in Chrome.

Common issues

"Element not found"

If find() returns empty results:

1. Re-capture first — call snapshot() before find(). Search operates on the cached tree.
2. Try broader queries — find(query="button") instead of find(query="submit primary button").
3. Check the tree — print the snapshot output and look for the element. It may have a different name than expected.
4. Check the scope — if the element is in a different window, use scope="full" with an app filter.
5. Check visibility — some elements have {offscreen} or {hidden} states and may not appear in the pruned tree. Use detail="full" to include them.

"Empty tree" or minimal output

• macOS: Missing accessibility permissions. See the macOS section above.
• Linux: AT-SPI2 not enabled. See the Linux section above.
• Windows: The app may be elevated (Run as Administrator) while your script is not.
• Any platform: The app may be loading. Add a short delay and re-capture.

"Action failed" but element exists

• Stale IDs — the element ID was from a previous snapshot. Re-capture and re-find.
• Element not interactable — the element may be disabled ({disabled} state), off-screen, or behind another window.
• Wrong action type — e.g., using click on a text field instead of type, or toggle on a non-checkbox element.

Batch action stops partway

batch() stops on the first failed action. Check the returned results list — it will contain results up to and including the failure. Fix the failing action and retry from that point.

FAQ

What's next?

• Error handling — all error types and recovery patterns
• Platform guides — platform-specific setup details