SeleniumHQ/selenium · error · ArgumentError

Safari does not support options that are not namespaced

Error message

Safari does not support options that are not namespaced

What it means

Safari::Options#add_option overrides the base Options#add_option to enforce that every capability key passed to safaridriver must be vendor-namespaced (contain a ':'). safaridriver rejects non-namespaced (W3C-standard) custom options at the protocol level, so the Ruby binding fails fast in Ruby rather than letting a malformed session request reach Apple's driver. Only the 'safari:' prefix and the predefined CAPABILITIES are accepted.

Source

Thrown at rb/lib/selenium/webdriver/safari/options.rb:35

# specific language governing permissions and limitations
# under the License.

module Selenium
  module WebDriver
    module Safari
      class Options < WebDriver::Options
        attr_accessor :options

        # @see https://developer.apple.com/documentation/webkit/about_webdriver_for_safari
        CAPABILITIES = {automatic_inspection: 'safari:automaticInspection',
                        automatic_profiling: 'safari:automaticProfiling',
                        experimental_web_socket_url: 'safari:experimentalWebSocketUrl'}.freeze
        BROWSER = 'safari'
        TECHNOLOGY_PREVIEW = 'Safari Technology Preview'

        def add_option(name, value = nil)
          key = name.is_a?(Hash) ? name.keys.first : name
          raise ArgumentError, 'Safari does not support options that are not namespaced' unless key.to_s.include?(':')

          super
        end

        def browser_name=(value)
          @options[:browser_name] = value
        end

        def browser_name
          @options[:browser_name] = Safari.technology_preview? ? TECHNOLOGY_PREVIEW : BROWSER
        end

        #
        # Enables WebDriver BiDi for Safari, which also requires the experimental capability, and
        # warns that Safari's BiDi support is experimental.
        #
        # @return [Boolean]
        #

View on GitHub (pinned to aa36b38e69)

Solutions

1. Prefix the key with a vendor namespace, e.g. add_option('myVendor:myOpt', value) or use a namespaced Symbol like add_option(:'custom:flag', true).
2. For built-in Safari capabilities use the predefined accessors (automatic_inspection:, automatic_profiling:, experimental_web_socket_url:) instead of add_option.
3. Branch your option-setting helper per browser so Safari keys always carry a ':' namespace.

Example fix

# before
options = Selenium::WebDriver::Safari::Options.new
options.add_option(:detach, true)

# after
options.add_option('custom:detach', true)

def namespaced?(key)
  k = key.is_a?(Hash) ? key.keys.first : key
  k.to_s.include?(':')
end

opt_name = :detach
if namespaced?(opt_name)
  safari_options.add_option(opt_name, true)
else
  safari_options.add_option("custom:#{opt_name}", true)
end

def safari_option_key?(key)
  k = key.is_a?(Hash) ? key.keys.first : key
  k.respond_to?(:to_s) && k.to_s.include?(':')
end

begin
  safari_options.add_option(name, value)
rescue ArgumentError => e
  raise unless e.message.include?('not namespaced')
  safari_options.add_option("vendor:#{name}", value)
end

When it happens

Trigger: Calling Selenium::WebDriver::Safari::Options#add_option with a bare Symbol/String key such as add_option(:detach, true), add_option('myOpt', 1), or add_option(foo: 1) where the key has no colon. Any key whose to_s does not include ':' triggers it.

Common situations: Copy-pasting Chrome/Firefox option code into a Safari test; using a generic helper that calls add_option across all browser Options classes with the same unprefixed key; assuming Safari accepts the same W3C extension keys as Chrome.

Related errors

• could not convert #{str.inspect} into color
• unexpected tag name #{tag_name.inspect}
• no capabilities provided for merge
• Capability keys must be strings: ${typeof key}
• Strategy can only be one of the following: normal, eager, no

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/f54839d2ef104a70. Report an issue: GitHub.