{"record":{"id":"0bac9f8b0409685d","repo":"teamcapybara/capybara","slug":"window-cannot-be-switched-inside-a-within-frame","errorCode":null,"errorMessage":"Window cannot be switched inside a `within_frame` block","messagePattern":"Window cannot be switched inside a `within_frame` block","errorType":"exception","errorClass":"Capybara::ScopeError","httpStatus":null,"severity":"error","filePath":"lib/capybara/session.rb","lineNumber":919,"sourceCode":"\n    def _find_frame(*args, **kw_args)\n      case args[0]\n      when Capybara::Node::Element\n        args[0]\n      when String, nil\n        find(:frame, *args, **kw_args)\n      when Symbol\n        find(*args, **kw_args)\n      when Integer\n        idx = args[0]\n        all(:frame, minimum: idx + 1)[idx]\n      else\n        raise TypeError\n      end\n    end\n\n    def _switch_to_window(window = nil, **options, &window_locator)\n      raise Capybara::ScopeError, 'Window cannot be switched inside a `within_frame` block' if scopes.include?(:frame)\n      raise Capybara::ScopeError, 'Window cannot be switched inside a `within` block' unless scopes.last.nil?\n\n      if window\n        driver.switch_to_window(window.handle)\n        window\n      else\n        synchronize_windows(options) do\n          original_window_handle = driver.current_window_handle\n          begin\n            _switch_to_window_by_locator(&window_locator)\n          rescue StandardError\n            driver.switch_to_window(original_window_handle)\n            raise\n          end\n        end\n      end\n    end\n","sourceCodeStart":901,"sourceCodeEnd":937,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/session.rb#L901-L937","documentation":"_switch_to_window is the internal switcher shared by switch_to_window and within_window. It refuses to run while any frame scope is on the stack (scopes.include?(:frame)), raising Capybara::ScopeError because frame and window switches cannot compose - switching windows would strand the frame scope.","triggerScenarios":"within_frame('chat') { switch_to_window(other_window) }; within_frame { within_window(-> { title == 'X' }) { ... } }; page-object frame helpers that switch windows before the frame block exits.","commonSituations":"Flows that open popups from inside iframes (payment/SSO frames); page objects nesting within_frame that also manage windows; refactors moving window code into frame-scoped helpers.","solutions":["Finish the within_frame block first, then switch windows at the top level","If a click inside the frame opens the window, return from the frame block before calling window_opened_by/switch_to_window","Design page objects so frame and window contexts never overlap"],"exampleFix":"# before\nwithin_frame('chat') do\n  switch_to_window(other_window) # Capybara::ScopeError\nend\n\n# after\nwithin_frame('chat') { click_link 'Open dashboard' }\nswitch_to_window(other_window)","handlingStrategy":"validation","validationCode":"switch_to_window(other_window) unless page.send(:scopes).include?(:frame)","typeGuard":null,"tryCatchPattern":"begin\n  switch_to_window(w)\nrescue Capybara::ScopeError => e\n  raise \"exit the within_frame block before switching windows (#{e.message})\"\nend","preventionTips":["Never manage windows from inside within_frame","Let frame blocks complete before any window operation"],"tags":["windows","frames","scope","within-frame","switch-to-window"],"backgroundTag":"window-scope-violation","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}