To understand UnreachableBrowserException, we should first understand how Selenium works. To most people, Selenium is simply an API that you use to write code to drive a browser. Notice that I said code, not tests. The Selenium API is designed to be a browser automation tool, not just a test tool. It is commonly used for testing, but it can be used for any purpose that would require browser automation.

The current API that is in use is the WebDriver API; the old Selenium RC API has been deprecated since Selenium 2 came out and should not be actively used by anybody creating a new project.

Selenium is a bit more than just an API though. It is also a series of plugins, or binaries, or native implementations that enable you to talk to the browser. The Selenium API talks to all of these implementation methods using the common wire protocol. This wire protocol is a RESTful web service using JSON over HTTP. When we talk about the bit of Selenium that commands are sent to using the wire protocol, we call it the RemoteWebDriver.

All browser-specific driver implementations are extensions of the core RemoteWebDriver class. The implementation method differs from driver to driver; some use client mode and some use server mode.

Client mode is where the RemoteWebDriver implementation is either loaded as a browser plugin or natively supported by the browser. The language bindings connect directly to the remote instance and tell it what to do. An example of this implementation method would be the old FirefoxDriver bindings (since Selenium 3, the FirefoxDriver implementation has switched from client mode to server mode and is on par with the ChromeDriver implementation):

Server mode is where the language binding sets up a server, which acts as a go-between for the language binding and the browser. It basically translates the commands sent by your code into something the browser can understand. An example of this implementation method would be ChromeDriver:

As you can see from the preceding diagram, the code you wrote using the WebDriver API is sent over to the browser via the RemoteWebDriver instance, using the wire protocol. As you can imagine, this process is problematic if there is no browser available for us to talk to.

If we send commands out but cannot get a response, we get UnreachableBrowserException; it means that you cannot connect to the RemoteWebDriver instance. There are various problems that could cause this error:

• The browser didn't start
• The browser crashed
• The version of the RemoteWebDriver instance you are using is incompatible with the version of the browser you are using
• Network issues
• Are you connecting to another machine?
• Is a firewall involved?
• Are you connecting to the correct port?
• The browser you are trying to use has not been installed
• The browser is not installed in the default location and Selenium can't find it

Debugging the issue can be frustrating, and you will probably kick yourself when you find out what the root cause was.