{"record":{"id":"aa6fd2bedda37e01","repo":"teamcapybara/capybara","slug":"unknown-format-selector-format","errorCode":null,"errorMessage":"Unknown format: #{selector_format}","messagePattern":"Unknown format: #(.+?)","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/capybara/queries/selector_query.rb","lineNumber":263,"sourceCode":"        hints[:texts] = text_fragments unless selector_format == :xpath\n        hints[:styles] = options[:style] if use_default_style_filter?\n        hints[:position] = true if use_spatial_filter?\n\n        case selector_format\n        when :css\n          if node.method(:find_css).arity == 1\n            node.find_css(css)\n          else\n            node.find_css(css, **hints)\n          end\n        when :xpath\n          if node.method(:find_xpath).arity == 1\n            node.find_xpath(xpath(exact))\n          else\n            node.find_xpath(xpath(exact), **hints)\n          end\n        else\n          raise ArgumentError, \"Unknown format: #{selector_format}\"\n        end\n      end\n\n      def to_element(node)\n        if @resolved_node.is_a?(Capybara::Node::Base)\n          Capybara::Node::Element.new(@resolved_node.session, node, @resolved_node, self)\n        else\n          Capybara::Node::Simple.new(node)\n        end\n      end\n\n      def valid_keys\n        (VALID_KEYS + custom_keys).uniq\n      end\n\n      def matches_node_filters?(node, errors)\n        applied_filters << :node\n","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/teamcapybara/capybara/blob/15b5fdb76e972e9623d5af2123ed3755594f9732/lib/capybara/queries/selector_query.rb#L245-L281","documentation":"SelectorQuery#resolve iterates node.find_css for :css format and node.find_xpath for :xpath; any other value hits the else branch and raises ArgumentError \"Unknown format: <format>\". The format comes from the selector definition (@selector.format), so this error means a selector was registered (Capybara.add_selector) with a format the query engine cannot dispatch — typically a custom selector whose format is nil, :expression, or misspelled.","triggerScenarios":"Capybara.add_selector(:foo) { xpath { ... } } without format :xpath on a query path that expects a driver call; custom selector with format: :html or a typo like :CSS; a selector defined with expression only (no format) being resolved against a driver node; monkey-patched/old selectors after upgrading Capybara where format handling changed.","commonSituations":"Writing project-specific selectors (data-test-id helpers) and forgetting format: :css/:xpath, copying selector definitions from gems that rely on expression objects a driver cannot use, case-sensitive symbol typos, custom selectors evaluated in within_frame/section code paths that call resolve directly.","solutions":["Set an explicit supported format in the selector definition: Capybara.add_selector(:role) { css { |r| \"[role='#{r}']\" }; format(:css) } — check your Capybara version's DSL (format :css vs format(:css))","Use only :css or :xpath; for complex matching build the expression in those languages or use filter blocks","Verify the error value: the message echoes the bad format symbol, which pinpoints the definition at fault","If the selector came from a gem/plugin, update it to a version compatible with your Capybara release"],"exampleFix":"# before\nCapybara.add_selector(:data_test) do\n  css { |id| \"[data-test='#{id}']\" }  # no format declared on some code paths\nend\n\n# after\nCapybara.add_selector(:data_test) do\n  css { |id| \"[data-test='#{id}']\" }\n  format(:css)\nend","handlingStrategy":"validation","validationCode":"fmt = Capybara::Selector.new(:probe, &proc {}).format rescue nil\n# simpler: assert on your registration before use\nsupported = %i[css xpath]\nraise 'fix selector format' unless supported.include?(:css)","typeGuard":"def supported_format?(fmt)\n  %i[css xpath].include?(fmt)\nend","tryCatchPattern":"begin\n  find(:data_test, 'submit')\nrescue ArgumentError => e\n  raise unless e.message.start_with?('Unknown format')\n  find(:css, \"[data-test='submit']\") # bypass the broken custom selector\nend","preventionTips":["Always declare format :css or format :xpath in Capybara.add_selector blocks","Cover custom selectors with a smoke test that calls find once after registration","After upgrading Capybara, re-run suites that define project-local selectors"],"tags":["capybara","argumenterror","custom-selector","format","css","xpath"],"backgroundTag":"unknown-selector-format","analyzedSha":"15b5fdb76e972e9623d5af2123ed3755594f9732","analyzedAt":"2026-08-21T16:53:45.588Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}