What causes "Window size not stable within #{seconds} seconds." in teamcapybara/capybara?

Retry the resize/maximize once or twice with a short delay; transient driver flakiness usually stabilizes on the second attempt.

teamcapybara/capybara · error · Capybara::WindowError

Window size not stable within #{seconds} seconds.

Error message

Window size not stable within #{seconds} seconds.

What it means

Window#resize_to and Window#maximize call the driver and then poll the window size every 0.025s until two consecutive reads are identical, bounded by default_max_wait_time. If the reported size keeps fluctuating until the timer expires, Capybara raises Capybara::WindowError with this message. It signals an unstable window/viewport, not that the resize command failed outright.

Source

Thrown at lib/capybara/window.rb:139

      [@session, @handle].hash
    end

    def inspect
      "#<Window @handle=#{@handle.inspect}>"
    end

  private

    def wait_for_stable_size(seconds = session.config.default_max_wait_time)
      res = yield if block_given?
      timer = Capybara::Helpers.timer(expire_in: seconds)
      loop do
        prev_size = size
        sleep 0.025
        return res if prev_size == size
        break if timer.expired?
      end
      raise Capybara::WindowError, "Window size not stable within #{seconds} seconds."
    end
  end
end

View on GitHub (pinned to 15b5fdb76e)

Solutions

Retry the resize/maximize once or twice with a short delay; transient driver flakiness usually stabilizes on the second attempt.
Increase Capybara.default_max_wait_time (or the session's default_max_wait_time) so the polling loop has time to settle.
Prefer fixing the window size at driver registration (Selenium chrome args '--window-size=1024,768' or browser options) instead of calling resize_to in CI.
For headless/Xvfb runs, configure a fixed display/screen size so maximize resolves to a deterministic geometry.

Example fix

# before
page.current_window.resize_to(1024, 768) # raises Capybara::WindowError on flaky CI

# after
begin
  page.current_window.resize_to(1024, 768)
rescue Capybara::WindowError
  sleep 0.5
  retry
end

Defensive patterns

Strategy: retry

Validate before calling

def stable_resize_to!(window, width, height, attempts: 3)
  window.resize_to(width, height)
rescue Capybara::WindowError
  attempts -= 1
  raise if attempts.zero?
  sleep 0.5
  retry
end

Try / catch

begin
  page.current_window.resize_to(1024, 768)
rescue Capybara::WindowError => e
  sleep 0.5
  retry if (attempts -= 1).positive? # initialize attempts = 2 before begin
  raise e # surface persistent instability after bounded retries
end

Prevention

Pin the window size in the driver registration (Selenium chrome args --window-size=W,H) instead of runtime resize on CI.
Keep Capybara.default_max_wait_time generous enough for resize polling on loaded Grid nodes.
Give Xvfb/headless environments a fixed screen geometry so maximize has a deterministic target.
Wrap resize_to/maximize in a bounded retry helper once, in a shared spec helper, rather than ad hoc in each spec.

When it happens

Trigger: page.current_window.resize_to(1024, 768) or page.current_window.maximize while the window manager or driver keeps reporting changing sizes: continuous CSS/layout thrash affecting the viewport, remote Selenium Grid nodes under load, Xvfb without a window manager (maximize has no stable target), or mobile-emulation viewports.

Common situations: CI (headless Chrome, Xvfb, Docker, BrowserStack/Sauce/LambdaTest) where resizing is flaky; default_max_wait_time set low; responsive-design test suites calling resize_to between examples.

Related errors

AI-assisted analysis of teamcapybara/capybara@15b5fdb76e (2026-08-21). Data as JSON: /api/errors/9bb9cffea17d5e69. Report an issue: GitHub.