{"record":{"id":"76f2cf4283748969","repo":"SeleniumHQ/selenium","slug":"options-must-be-an-instance-of-default-options","errorCode":null,"errorMessage":":options must be an instance of #{default_options.class}","messagePattern":":options must be an instance of #(.+?)","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"rb/lib/selenium/webdriver/common/local_driver.rb","lineNumber":49,"sourceCode":"        begin\n          yield(caps, http_client) if block_given?\n        rescue Selenium::WebDriver::Error::WebDriverError\n          @service_manager&.stop\n          raise\n        end\n      end\n\n      def service_url(service)\n        @service_manager = service.launch\n        @service_manager.uri\n      end\n\n      def process_options(options, service)\n        default_options = Options.send(browser)\n        options ||= default_options\n\n        unless options.is_a?(default_options.class)\n          raise ArgumentError, \":options must be an instance of #{default_options.class}\"\n        end\n\n        finder = WebDriver::DriverFinder.new(options, service)\n        options.binary = finder.browser_path if options.respond_to?(:binary) && finder.browser_path?\n        service.executable_path = finder.driver_path\n        options.browser_version = nil if options.respond_to?(:binary) && options.binary\n        options.as_json\n      end\n\n      private\n\n      def assert_local_arguments(url, http_client, client_config)\n        if url || client_config&.server_url\n          raise ArgumentError, \"Can't set the server URL for #{self.class}; the service provides it\"\n        elsif http_client && client_config\n          raise ArgumentError, 'Cannot use both :http_client and :client_config'\n        end\n      end","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/rb/lib/selenium/webdriver/common/local_driver.rb#L31-L67","documentation":"When starting a local driver, process_options validates that the supplied :options object is an instance of the Options subclass that matches the target browser (e.g. Chrome::Options for Chrome, Firefox::Options for Firefox). If the options object's class does not match, ArgumentError is raised. This prevents silently sending the wrong capability payload to the driver service.","triggerScenarios":"Passing Selenium::WebDriver::Firefox::Options.new as :options to Selenium::WebDriver.for(:chrome, options:). Passing a plain Hash or a remote Capabilities object instead of an Options instance. Mixing Edge::Options with a Chrome driver.","commonSituations":"Copy-pasting an Options setup block from another browser and changing only the :browser symbol. Switching the browser without updating the Options class. Passing an Options object whose class is a parent or unrelated type.","solutions":["Construct the Options class that matches the browser: Selenium::WebDriver::Chrome::Options.new for :chrome.","If you do not need custom options, omit the :options argument so Selenium uses the default Options.send(browser) instance.","Double-check that the symbol passed to Driver.for matches the Options subclass you instantiated."],"exampleFix":"# before\noptions = Selenium::WebDriver::Firefox::Options.new\ndriver = Selenium::WebDriver.for(:chrome, options: options)\n\n# after\noptions = Selenium::WebDriver::Chrome::Options.new\ndriver = Selenium::WebDriver.for(:chrome, options: options)","handlingStrategy":"type-guard","validationCode":"expected = Selenium::WebDriver::Options.send(browser).class\nraise ArgumentError, \"options must be #{expected}\" unless options.is_a?(expected)","typeGuard":"def options_match_browser?(options, browser)\n  options.is_a?(Selenium::WebDriver::Options.send(browser).class)\nend","tryCatchPattern":"begin\n  Selenium::WebDriver.for(browser, options: options)\nrescue ArgumentError => e\n  raise unless e.message.include?('must be an instance of')\n  options = Selenium::WebDriver::Options.send(browser)\n  Selenium::WebDriver.for(browser, options: options)\nend","preventionTips":["Keep the :browser symbol and the Options subclass in sync in a single config object.","Derive the Options class from the browser symbol: Selenium::WebDriver::Options.send(browser).","Omit :options when you only need defaults."],"tags":["ruby","driver-init","options","local-driver"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}