teamcapybara/capybara · error · ArgumentError

Capybara.app_host should be set to a url (http://www.example

Error message

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

What it means

Session::Config#app_host= validates the assigned value against a URI regexp: it must be a full URL with scheme (http://www.example.com) or nil. Assigning a bare host ('www.example.com'), host:port ('localhost:3000'), or a path raises ArgumentError at configuration time, naming the offending value. The parallel default_host= setter has the same rule.

Source

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

    remove_method :server_host

    ##
    #
    # @return [String]    The IP address bound by default server
    #
    def server_host
      @server_host || '127.0.0.1'
    end

    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.

View on GitHub (pinned to 15b5fdb76e)

Solutions

Include the scheme: Capybara.app_host = 'http://www.example.com'
Normalize env input before assigning: prefix http:// (or https://) when the scheme is missing
Set nil to clear the value; remember default_host= has the same requirement

Example fix

# before
Capybara.app_host = ENV['APP_HOST'] # "staging.example.com" -> ArgumentError

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

Defensive patterns

Strategy: validation

Validate before calling

def normalize_base_url(raw)
  return nil if raw.nil? || raw.empty?
  raw.match?(%r{\Ahttps?://}) ? raw : "http://#{raw}"
end

Capybara.app_host = normalize_base_url(ENV['APP_HOST'])

Type guard

def valid_url?(str)
  str.is_a?(String) && str.match?(URI::DEFAULT_PARSER.make_regexp)
end

Try / catch

begin
  Capybara.app_host = raw_host
rescue ArgumentError
  Capybara.app_host = "http://#{raw_host}"
end

Prevention

Store full URLs (scheme + host) in env config, never bare hostnames
Validate app_host/default_host in a boot check before the suite runs

When it happens

Trigger: Capybara.app_host = 'www.example.com' (no scheme); Capybara.app_host = ENV['APP_HOST'] where the env var lacks http://; assigning 'localhost:9292' or '/app'.

Common situations: CI env vars configured without the scheme; copying hostnames from deployment configs or tickets; multi-environment suites where some env files store bare hosts.

Related errors

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