Claude Computer Use Coordinate Out of Bounds — Click Fix (2026) | AI Error Hub

Anthropic Claude Computer Use Severity: High Client-side execution

Claude Computer Use — Coordinate Out of Bounds

Claude requests a click at coordinates outside your display. Root cause is usually a mismatch: Claude sees the screenshot at one resolution but you're executing at another. Anthropic recommends declaring a specific resolution and downscaling screenshots to match.

Error surface: Client tool execution Category: Computer Use Common symptom: Click misses target Last tested: Nov 15, 2026

Quick Fix (TL;DR)

Declare display as 1280×800 in the tool config, capture screenshots at your actual resolution, then downscale to 1280×800 before returning to Claude. Claude clicks in the declared coordinate space; your executor scales those clicks up to actual resolution. Always clamp coordinates to display bounds as a safety net.

The Error Symptoms

Common failure modes

pyautogui.FailSafeException: coordinates out of screen bounds
  → Claude sent x=1500 but your screen is 1280 wide

Click executed but nothing happened
  → Coordinate mismatch: clicked empty space instead of button

Xlib error: BadValue for XWarpPointer
  → Negative coordinates or way beyond display

Agent stuck in a loop clicking wrong location
  → Claude sees old screenshot, keeps aiming at stale coordinates

Screenshot is 1920x1080 but tool declared 1280x800
  → Coordinate space mismatch — need to scale

How Coordinates Actually Work in Computer Use

The two coordinate spaces

Claude's space: Whatever dimensions you declared in the tool config (e.g., 1280×800). Claude analyzes screenshots you provided at these dimensions and returns click coordinates within them.
Actual display space: Your real screen (e.g., 1920×1080). To execute Claude's click, scale from Claude's space to your actual space.

Coordinate flow diagram
┌─────────────────────────────────────────────────────────┐
│  1. Take REAL screenshot (1920×1080)                    │
│  2. Downscale to declared size (1280×800)               │
│  3. Return downscaled image in tool_result              │
│  4. Claude analyzes at 1280×800, returns click (400,600)│
│  5. You SCALE UP: 400 × (1920/1280) = 600               │
│                    600 × (1080/800)  = 810              │
│  6. Execute click at real (600, 810)                    │
└─────────────────────────────────────────────────────────┘

What Actually Causes This Error

45%

Screenshot resolution != declared tool resolutionSent 1920×1080 screenshot but declared 1280×800. Claude's coordinates fit 1920×1080 but you execute in 1280×800.

25%

No downscaling — declared wrong dimensionsDeclared actual display (e.g., 3840×2160 4K). Claude struggles with such large coordinates.

15%

HiDPI/Retina display scalingScreenshot is 2× logical resolution. Claude's coordinates are in physical pixels but display uses logical.

Not clamping click coordinatesRare Claude mistake OR scaling math bug produces (x=1350, y=-5).

Cross-monitor confusionMulti-display setup. Claude sees screen 1, executor targets screen 2.

Fixes That Work (Tested Nov 2026)

1Anthropic's Recommended Resolution

Anthropic recommends declaring one of these standard resolutions to maximize Claude's accuracy:

Recommended Size	Aspect	Use for
1280 × 800	16:10	General desktop (RECOMMENDED)
1366 × 768	16:9	Common laptop resolution
1024 × 768	4:3	Legacy applications

Claude's vision was calibrated on these ranges. Avoid 4K or ultrawide declarations — accuracy drops.

Python · declare standard resolution
DECLARED_WIDTH = 1280
DECLARED_HEIGHT = 800

tools = [{
    "type": "computer_20250124",
    "name": "computer",
    "display_width_px": DECLARED_WIDTH,
    "display_height_px": DECLARED_HEIGHT,
    "display_number": 1,
}]

2Coordinate Scaling Utility

Python · scale + clamp
import pyautogui
from PIL import Image
import mss

class CoordinateMapper:
    def __init__(self, declared_w=1280, declared_h=800):
        self.declared_w = declared_w
        self.declared_h = declared_h
        # Detect actual display size
        with mss.mss() as sct:
            m = sct.monitors[1]
            self.actual_w = m["width"]
            self.actual_h = m["height"]
        self.scale_x = self.actual_w / self.declared_w
        self.scale_y = self.actual_h / self.declared_h
    
    def to_actual(self, claude_x, claude_y):
        """Convert Claude's coord (declared space) to actual display."""
        # Clamp Claude's coords first
        cx = max(0, min(claude_x, self.declared_w - 1))
        cy = max(0, min(claude_y, self.declared_h - 1))
        # Scale to real display
        real_x = int(cx * self.scale_x)
        real_y = int(cy * self.scale_y)
        # Final safety clamp
        real_x = max(0, min(real_x, self.actual_w - 1))
        real_y = max(0, min(real_y, self.actual_h - 1))
        return real_x, real_y
    
    def screenshot_downscaled(self):
        """Take actual screenshot, downscale to declared size."""
        with mss.mss() as sct:
            raw = sct.grab(sct.monitors[1])
            img = Image.frombytes("RGB", raw.size, raw.bgra, "raw", "BGRX")
        img = img.resize((self.declared_w, self.declared_h), Image.LANCZOS)
        return img

mapper = CoordinateMapper(1280, 800)

# Handle Claude's click
def handle_click(action):
    x, y = action["coordinate"]
    real_x, real_y = mapper.to_actual(x, y)
    try:
        pyautogui.click(real_x, real_y)
        return f"Clicked at ({real_x}, {real_y}) — Claude asked for ({x}, {y})"
    except pyautogui.FailSafeException:
        return f"FailSafe: refused click at ({real_x}, {real_y})"

3Handle HiDPI / Retina Correctly

HiDPI gotcha (macOS Retina, some Linux setups)

On HiDPI displays, the screenshot is captured at physical pixels (e.g., 2880×1800) while UI positions are logical (1440×900). You must handle both dimensions consistently. Solution: capture physical, downscale to your declared size (e.g., 1280×800), and scale clicks back up to logical coordinates (which is what pyautogui expects).

Python · HiDPI-aware executor
import subprocess

def get_logical_dimensions():
    """Get logical (not physical) screen size on macOS/Linux."""
    # macOS: use system_profiler
    try:
        result = subprocess.run(["xdpyinfo"], capture_output=True, text=True)
        for line in result.stdout.splitlines():
            if "dimensions:" in line:
                dims = line.split()[1].split("x")
                return int(dims[0]), int(dims[1])
    except Exception:
        pass
    # Fallback
    return pyautogui.size()

class HiDPIMapper(CoordinateMapper):
    def __init__(self, declared_w=1280, declared_h=800):
        self.declared_w = declared_w
        self.declared_h = declared_h
        # Screenshot dims (physical)
        with mss.mss() as sct:
            m = sct.monitors[1]
            self.screenshot_w, self.screenshot_h = m["width"], m["height"]
        # Click dims (logical)
        self.actual_w, self.actual_h = get_logical_dimensions()
        # Scaling from declared → logical for clicks
        self.scale_x = self.actual_w / self.declared_w
        self.scale_y = self.actual_h / self.declared_h

Preventing This Error Going Forward

Use one of Anthropic's recommended resolutions. 1280×800 works best.
Always downscale screenshots to declared dimensions. Never send raw 4K.
Scale Claude's coordinates before executing. Two coordinate spaces = math required.
Always clamp final coordinates. Safety net against math bugs.
Log intended vs actual click location. Debug misses quickly.
Handle HiDPI explicitly. Physical vs logical dimensions differ 2×.
Test with a known target first. Click a known-location button before real workload.

Tested by Sana K.
Researcher · AI Error Hub

Last verified: Nov 15, 2026 · Beta: computer-use-2025-01-24

Frequently Asked Questions

Claude's vision was calibrated on standard desktop resolutions. Very small (mobile-size) or very large (4K) screenshots have lower click accuracy. 1280×800 is the sweet spot for both cost (fewer tokens) and precision.

Claude returns integer coordinates. If you upscale from 1280×800 to 1920×1080, a Claude coord of (100, 100) becomes (150, 135). Sub-pixel precision doesn't matter for clicking — buttons are dozens of pixels wide.

Claude uses the scroll action explicitly. After scroll, take a new screenshot and return it. Claude will re-evaluate. Never scroll without returning a fresh screenshot — Claude will click at stale coordinates.

No — modern Claude models handle coordinates well without grids. Adding overlays confuses the visual model. Trust its native ability.

Yes with a two-tool pattern: use a separate high-res screenshot for reading (via image content block), keep computer tool at 1280×800 for clicks. Advanced but effective for dense UIs.