SeleniumHQ/selenium · error · Error::WebDriverError

unable to translate 'localhost' for TCP + IPv4

Error message

unable to translate 'localhost' for TCP + IPv4

What it means

Platform.localhost resolves the string 'localhost' to an IPv4 address via Socket.getaddrinfo. If the call returns an empty list (no address info), it raises WebDriverError. This indicates the local system cannot resolve 'localhost' over TCP/IPv4.

Source

Thrown at rb/lib/selenium/webdriver/common/platform.rb:158

        assert_file(path)

        return if File.executable? path

        raise Error::WebDriverError, "not executable: #{path.inspect}"
      end

      def exit_hook
        pid = Process.pid

        at_exit { yield if Process.pid == pid }
      end

      def localhost
        info = Socket.getaddrinfo 'localhost', 80, Socket::AF_INET, Socket::SOCK_STREAM

        return info[0][3] unless info.empty?

        raise Error::WebDriverError, "unable to translate 'localhost' for TCP + IPv4"
      end

      def ip
        orig = Socket.do_not_reverse_lookup
        Socket.do_not_reverse_lookup = true

        begin
          UDPSocket.open do |s|
            s.connect '8.8.8.8', 53
            return s.addr.last
          end
        ensure
          Socket.do_not_reverse_lookup = orig
        end
      rescue Errno::ENETUNREACH, Errno::EHOSTUNREACH
        # no external ip
      end

View on GitHub (pinned to aa36b38e69)

Solutions

1. Ensure /etc/hosts contains a '127.0.0.1 localhost' entry.
2. In containers, use an image that includes a proper hosts file or configure it at startup.
3. Verify with Socket.getaddrinfo('localhost', 80, Socket::AF_INET, Socket::SOCK_STREAM) on the host.

info = Socket.getaddrinfo('localhost', 80, Socket::AF_INET, Socket::SOCK_STREAM)
raise 'localhost unresolvable; check /etc/hosts' if info.empty?

begin
  Selenium::WebDriver::Platform.localhost
rescue Selenium::WebDriver::Error::WebDriverError => e
  raise unless e.message.include?('localhost')
  '127.0.0.1'
end

When it happens

Trigger: Running in a container or sandbox whose /etc/hosts lacks a localhost entry. A broken or minimal DNS/hosts configuration. Network namespace where localhost resolution is unavailable.

Common situations: Docker/container images with a stripped /etc/hosts. Sandboxed CI runners with restricted networking. Systems where IPv4 loopback is disabled.

Related errors

• remote server not stopped in #{@timeout} seconds
• Unknown pattern type: #{pattern_type}
• unknown os: #{host_os.inspect}
• not a file: #{path.inspect}
• not executable: #{path.inspect}

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