Textualize/textual · error · OutOfBounds

Target offset is outside of currently-visible screen region.

Error message

Target offset is outside of currently-visible screen region.

What it means

Raised by Textual's Pilot when simulating mouse events at coordinates that fall outside the visible screen region. It is a test-time guard ensuring synthesized clicks target an actual on-screen position.

Source

Thrown at src/textual/pilot.py:442

        if widget is None:
            target_widget = screen
        elif isinstance(widget, Widget):
            target_widget = widget
        else:
            target_widget = screen.query_one(widget)

        message_arguments = _get_mouse_message_arguments(
            target_widget,
            offset,
            button=button,
            shift=shift,
            meta=meta,
            control=control,
        )

        offset = Offset(message_arguments["x"], message_arguments["y"])
        if offset not in screen.size.region:
            raise OutOfBounds(
                "Target offset is outside of currently-visible screen region."
            )

        widget_at = None
        for chain in range(1, times + 1):
            for mouse_event_cls in events:
                await self.pause()
                # Get the widget under the mouse before the event because the app might
                # react to the event and move things around. We override on each iteration
                # because we assume the final event in `events` is the actual event we care
                # about and that all the preceding events are just setup.
                # E.g., the click event is preceded by MouseDown/MouseUp to emulate how
                # the driver works and emits a click event.
                kwargs = message_arguments
                if mouse_event_cls is Click:
                    kwargs = {**kwargs, "chain": chain}

                if widget_at is None:

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Pass a selector or widget instead of raw coordinates and let Pilot compute the offset
2. Clamp coordinates to within screen.size
3. Run the test with a larger terminal: app.run_test(size=(100, 40))

Example fix

// before
await pilot.click(90, 30)
// after
async with app.run_test(size=(120, 50)) as pilot:
    await pilot.click(90, 30)

if Offset(x, y) in app.screen.size.region:
    await pilot.click(x, y)

When it happens

Trigger: Calling pilot.click(), pilot.mouse_down(), pilot.mouse_up(), or pilot.hover() with x/y offsets (or an offset plus a widget whose combined position) that exceeds the screen size (default 80x24 in tests).

Common situations: Clicking a widget near the right/bottom edge of a small default test terminal, or passing absolute coordinates larger than the test console dimensions without setting a custom size in run_test().

Related errors

• Timed out while waiting for widgets to process pending messa
• Can't animate attribute {attribute!r} on {obj!r}; attribute
• Don't know how to animate {value!r}; Can only animate <int>,
• Can't encode {datum!r}
• must be bytes

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/0e6a6eb512ee6aec. Report an issue: GitHub.