SeleniumHQ/selenium · error · Error::WebDriverError

unexpected response, code=#{code}, content-type=#{content_ty

Error message

unexpected response, code=#{code}, content-type=#{content_type.inspect}

What it means

Raised as Error::WebDriverError by Http::Common#create_response when the response has a non-JSON content-type, is not a 204 (No Content), and the body is empty. This is the catch-all for unexpected HTTP responses that the client cannot parse into a W3C response — neither JSON to parse nor an explicit no-content status.

Source

Thrown at rb/lib/selenium/webdriver/remote/http/common.rb:152

            raise Error::WebDriverError,
                  "Unable to encode string to UTF-8: #{e.message}. " \
                  "String encoding: #{str.encoding}, content: #{str.inspect}"
          end

          def create_response(code, body, content_type)
            code = code.to_i
            body = body.to_s.strip
            content_type = content_type.to_s
            WebDriver.logger.debug("<- #{body}", id: :command)

            if content_type.include? CONTENT_TYPE
              raise Error::WebDriverError, "empty body: #{content_type.inspect} (#{code})\n#{body}" if body.empty?

              Response.new(code, JSON.parse(body))
            elsif code == 204
              Response.new(code)
            else
              msg = if body.empty?
                      "unexpected response, code=#{code}, content-type=#{content_type.inspect}"
                    else
                      "unexpected response, code=#{code}, content-type=#{content_type.inspect}\n#{body}"
                    end

              raise Error::WebDriverError, msg
            end
          end
        end # Common
      end # Http
    end # Remote
  end # WebDriver
end # Selenium

View on GitHub (pinned to aa36b38e69)

Solutions

Verify the remote URL points to the correct Selenium Server endpoint (e.g. http://host:4444 or with /wd/hub if required by server version).
Check if a proxy, firewall, or WAF is intercepting requests to the remote endpoint.
Enable header debug logging (id: :header) to inspect the full response content-type and code.
Curl the endpoint directly to see what it returns: curl -v http://host:4444/status.

Example fix

# before
driver = Selenium::WebDriver.for(:remote, url: 'http://grid:4444/wd/hub', ...)
# server returns text/html empty body (wrong endpoint)

# after — verify the correct endpoint
driver = Selenium::WebDriver.for(:remote, url: 'http://grid:4444', ...)
# confirm with: curl -s http://grid:4444/status

Defensive patterns

Strategy: validation

Validate before calling

# Validate the remote URL is reachable and returns a proper status:
require 'net/http'
uri = URI(server_url + '/status')
resp = Net::HTTP.get_response(uri)
raise 'Unexpected endpoint' unless resp.content_type.include?('application/json')

Try / catch

begin
  Selenium::WebDriver.for(:remote, url: server_url, options: opts)
rescue Selenium::WebDriver::Error::WebDriverError => e
  raise unless e.message.include?('unexpected response')
  raise "Remote endpoint #{server_url} is not a valid Selenium Server"
end

Prevention

Verify the remote URL points to a Selenium Server endpoint before driver creation.
Curl the /status endpoint to confirm it returns JSON.
Check for proxies, firewalls, or WAFs intercepting grid traffic.

When it happens

Trigger: The server returns an HTML error page with a non-JSON content-type but empty body. A 200 response with content-type text/html and no body. A 302 redirect body that was consumed. An intermediate proxy returning an empty error page.

Common situations: Pointing the WebDriver client at the wrong URL (e.g. a web app root instead of the Selenium Server /wd/hub endpoint). A firewall or WAF returning empty blocking responses. Server misconfiguration returning wrong content-types. Authentication challenges (401) with empty bodies from proxies.

Related errors

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