teamcapybara/capybara · error · ArgumentError

Capybara.default_host should be set to a url (http://www.exa

Error message

Capybara.default_host should be set to a url (http://www.example.com). Attempted to set #{url.inspect}.

What it means

Capybara validates the global app_host/default_host configuration setters: any non-nil value must fully match Ruby's URI regular expression, i.e. include a scheme such as http:// or https://. When the value fails that match, the setter raises ArgumentError immediately rather than storing a malformed host that would later produce broken request URLs. nil is explicitly allowed and clears the setting.

Source

Thrown at lib/capybara/session/config.rb:99

    remove_method :server_errors=
    def server_errors=(errors)
      (@server_errors ||= []).replace(errors.dup)
    end

    remove_method :app_host=
    def app_host=(url)
      unless url.nil? || url.match?(URI_PARSER.make_regexp)
        raise ArgumentError, "Capybara.app_host should be set to a url (http://www.example.com). Attempted to set #{url.inspect}."
      end

      @app_host = url
    end

    remove_method :default_host=
    def default_host=(url)
      unless url.nil? || url.match?(URI_PARSER.make_regexp)
        raise ArgumentError, "Capybara.default_host should be set to a url (http://www.example.com). Attempted to set #{url.inspect}."
      end

      @default_host = url
    end

    remove_method :test_id=
    ##
    #
    # Set an attribute to be optionally matched against the locator for builtin selector types.
    # This attribute will be checked by builtin selector types whenever id would normally be checked.
    # If `nil` then it will be ignored.
    #
    # @param [String, Symbol, nil] id Name of the attribute to use as the test id
    #
    def test_id=(id)
      @test_id = id&.to_sym
    end

View on GitHub (pinned to 15b5fdb76e)

Solutions

1. Set a full URL including scheme: Capybara.default_host = 'http://www.example.com' (same form for app_host).
2. If the value comes from ENV, normalize it first: host = ENV['APP_HOST']; host = "http://#{host}" unless host.nil? || host.match?(%r{\Ahttps?://}).
3. Pass nil to clear the setting; the setter accepts nil without raising.
4. Check for whitespace/newlines or malformed schemes in the value before assigning (e.g. value.strip and a URI::DEFAULT_PARSER.make_regexp match).

Example fix

# before
Capybara.app_host = ENV['APP_HOST'] # raises ArgumentError if APP_HOST=www.example.com

# after
app_host = ENV['APP_HOST']
app_host = "http://#{app_host}" unless app_host.nil? || app_host.start_with?('http://', 'https://')
Capybara.app_host = app_host

require 'uri'

def safe_host=(value)
  return if value.nil?
  raise ArgumentError, "#{value.inspect} is not a full URL" unless value.match?(URI::DEFAULT_PARSER.make_regexp)
  Capybara.app_host = value
end

def valid_capybara_host?(value)
  value.nil? || (value.is_a?(String) && value.match?(URI::DEFAULT_PARSER.make_regexp))
end

begin
  Capybara.default_host = ENV['DEFAULT_HOST']
rescue ArgumentError => e
  abort "Fix DEFAULT_HOST to include http:// or https://: #{e.message}"
end

When it happens

Trigger: Calling Capybara.app_host=, Capybara.default_host= (or session.config.app_host= / session.config.default_host=) with a scheme-less string such as 'www.example.com' or 'localhost:3000'. Typical culprit: Capybara.app_host = ENV['APP_HOST'] where the environment variable holds only a hostname or host:port.

Common situations: Reading host settings from environment variables or .env files that omit the scheme (or contain a typo like 'http:/example.com' or a trailing newline); configuring app_host for browser drivers (Selenium) or external test apps; conflating default_host (host used for host-relative URLs under rack_test) with app_host (base URL for visit with absolute paths) during setup.

Related errors

• rack-test requires a rack application, but none was given
• You must specify both x: and y: for a click offset
• Invalid option(s) #{invalid_names}, should be one of #{valid
• Match queries don't support quantity options. Invalid keys -
• Unused parameters passed to #{self.class.name} : #{args}

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