SeleniumHQ/selenium · error · Error::WebDriverError

Unable to encode string to UTF-8: #{e.message}. String encod

Error message

Unable to encode string to UTF-8: #{e.message}. String encoding: #{str.encoding}, content: #{str.inspect}

What it means

Raised as Error::WebDriverError by Http::Common#encode_string_to_utf8 when the response body string cannot be converted to UTF-8. The method first checks for already-valid UTF-8, then tries force_encoding for binary encodings, then str.encode(UTF_8); if all fail with an EncodingError, it wraps the failure with the original encoding and content for diagnostics.

Source

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

              obj.each_with_object({}) do |(key, value), result|
                result[ensure_utf8_encoding(key)] = ensure_utf8_encoding(value)
              end
            else
              obj
            end
          end

          def encode_string_to_utf8(str)
            return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?

            if BINARY_ENCODINGS.include?(str.encoding)
              result = str.dup.force_encoding(Encoding::UTF_8)
              return result if result.valid_encoding?
            end

            str.encode(Encoding::UTF_8)
          rescue EncodingError => e
            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?

View on GitHub (pinned to aa36b38e69)

Solutions

1. Check the remote server and browser locale/encoding settings; configure them to use UTF-8.
2. If the error is intermittent, capture the raw response via debug logging (id: :command) to identify the problematic byte sequence.
3. Update the Selenium Server/Grid to a version that normalizes response encodings.
4. If the content is genuinely non-text (e.g. a screenshot or crash dump), verify you are calling the correct endpoint.

Example fix

# No caller-side code fix; this is a server/network encoding issue.
# Enable logging to diagnose:
# Selenium::WebDriver::WebDriver.logger.level = :debug
# Then inspect the logged "<- ..." response body for encoding issues.

# No caller-side prevention; this depends on server response encoding.
# You can enable debug logging to capture responses for diagnosis:
# Selenium::WebDriver.logger.level = :debug

begin
  driver.navigate.to(url)
rescue Selenium::WebDriver::Error::WebDriverError => e
  raise unless e.message.include?('Unable to encode string to UTF-8')
  WebDriver.logger.error("Encoding error from server: #{e.message}", id: :command)
  retry
end

When it happens

Trigger: The remote server returns a response body in an encoding incompatible with UTF-8 (e.g. a legacy single-byte encoding with invalid byte sequences). A response containing binary garbage or a truncated multi-byte sequence. Content with mixed encodings concatenated server-side that produces invalid UTF-8 when forced.

Common situations: Scraping or interacting with pages whose server responses include non-UTF-8 characters in error messages or alert text. Remote nodes running on OSes with non-UTF-8 default encodings. Proxy or middleware corrupting response bodies. Browser crashes producing binary heap dumps in the response body.

Related errors

• #{name} expected an object on the wire, got #{json_payload.i
• #{name}##{field.name} is required but was missing from the r
• #{name}##{field.name} received null but is not nullable
• #{name}##{field.name} expected #{field.list ? 'a list' : 'a
• #{name}##{field.name} expected #{field.primitive}, got #{raw

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