WebDriver errors

Any WebDriver command that is sent to might plausibly receive an error response. An error is represented by an HTTP response with an HTTP status code in the 4xx or 5xx range, and a JSON payload holding details of the error.

Payload

The error object is a JSON Object that bears three, and sometimes four, fields:

error

Error type.

message

Human-readable description of the nature of the error.

stacktrace

Stacktrace report of the active stack frames at the time when the error occurred.

data (optional)

Arbitrary and implementation-defined data that it can be useful to present the user with.

Many drivers include the user prompt's text when encountering an unexpected alert open error.

Example

For example a GET request to /session/1234/url, where 1234 is a bogus session, would return a response with the 404 Not Found status and the following body:

json

{
  "value": {
    "error": "invalid session id",
    "message": "No active session with ID 1234",
    "stacktrace": ""
  }
}

It is optional for the driver to annotate errors with additional error data. Notably, this is common when a user prompt, such as window.alert, has opened a modal dialog after execution of your previous WebDriver command request.

Because both WebDriver and JavaScript execution is halted by such a dialog, we see an unexpected alert open error in the subsequent response:

json

{
  "value": {
    "error": "unexpected alert open",
    "message": "",
    "stacktrace": "",
    "data": {
      "text": "Message from window.alert"
    }
  }
}

In most clients the error would be represented by some sort of error type or object representation. In Python it is represented as a WebDriverException, in Node.js as a WebDriverError, and in Java also as a WebDriverException.

Table of errors

Error type HTTP status code Description
element click intercepted 400 Bad Request The Element Click command could not be completed because the element receiving the events is obscuring the element that was requested clicked.
element not interactable 400 Bad Request A command could not be completed because the element is not pointer- or keyboard interactable.
insecure certificate 400 Bad Request Navigation caused the user agent to hit a certificate warning, which is usually the result of an expired or invalid TLS certificate.
invalid argument 400 Bad Request The arguments passed to a command are either invalid or malformed.
invalid cookie domain 400 Bad Request An illegal attempt was made to set a cookie under a different domain than the current page.
invalid element state 400 Bad Request A command could not be completed because the element is in an invalid state, e.g. attempting to clear an element that isn't both editable and resettable.
invalid selector 400 Bad Request An element retrieval command provided an unknown selector strategy.
invalid session id 404 Not Found Given session ID is not recognized, meaning the session either does not exist of that it's not active. Note that a session that has been deleted cannot be re-used.
JavaScript error 500 Internal Server Error An error occurred while executing JavaScript supplied by the user.
move target out of bounds 500 Internal Server Error The target for mouse interaction is not in the browser's viewport and cannot be brought into that viewport.
no such alert 404 Not Found An attempt was made to operate on a user prompt when one was not open.
no such cookie 404 Not Found No cookie matching the given path name was found amongst the cookies of the current document.
no such element 404 Not Found An element could not be located on the page using the given search parameters.
no such frame 404 Not Found A command to switch to a frame could not be satisfied because the frame could not be found.
no such window 404 Not Found A command to switch to a window could not be satisfied because the window could not be found.
script timeout 408 Request Timeout A script did not complete before its timeout expired.
session not created 500 Internal Server Error A new session could not be created, either because the browser could not be started or because the provided capabilities to start the session did not match.
stale element reference 404 Not Found A command failed because the referenced element is no longer attached to the DOM.
timeout 408 Request Timeout An operation did not complete before its timeout expired.
unable to set cookie 500 Internal Server Error A command to set a cookie's value could not be satisfied.
unable to capture screen 500 Internal Server Error A screen capture was made impossible.
unexpected alert open 500 Internal Server Error A modal dialog was open, blocking this operation.
unknown command 404 Not Found A command could not be executed because the driver was unaware of it.
unknown error 500 Internal Server Error An unknown error occurred in the driver whilst processing the command.
unknown method 405 Method Not Allowed The requested command matched a known URL but did not match a method for that URL.
unsupported operation 500 Internal Server Error Indicates that a command that should have executed properly cannot be supported for some reason.

See also