Safaridriver Flags for Diagnosing Session Failures

This article provides a direct overview of the command-line flags accepted by safaridriver to diagnose and resolve session creation failures in the Safari web browser. It covers how to enable diagnostic logging, locate the generated log files, and use supplementary flags to troubleshoot permission and port issues that commonly prevent WebDriver sessions from starting.

The Primary Diagnostic Flag: --diagnose

When a WebDriver session fails to initialize, the most effective command-line tool is the --diagnose flag. Passing this argument instructs safaridriver to record detailed diagnostic information for every session hosted by that specific driver instance.

safaridriver --diagnose

When you run safaridriver with this flag, it logs all HTTP traffic, internal state changes, and error states. Because session creation failures mean a session ID might not yet exist, --diagnose is critical because it captures the startup sequence before a session is officially established.

Where to find the logs: All diagnostic files generated by this flag are written to the following directory on macOS: ~/Library/Logs/com.apple.WebDriver/

Troubleshooting Permissions: --enable

A very common cause for session creation failure in Safari is that the browser is not yet authorized to allow remote automation. By default, a user must manually enable the Develop menu and check "Allow Remote Automation."

You can diagnose and bypass this configuration failure from the command line using the --enable flag. This requires administrator privileges:

sudo safaridriver --enable

If your sessions were failing due to lack of authorization or hanging on security prompts, running this command once will resolve the issue and allow subsequent sessions to start without manual intervention.

Diagnosing Port Conflicts: -p or --port

Sometimes a session fails to create because the default port safaridriver attempts to bind to is already in use by another process or a hung WebDriver instance. safaridriver requires you to specify a port when launching it manually from the terminal.

You can test if a port conflict is causing your session failures by launching the driver on a known open port using the -p or --port flag:

safaridriver -p 0

Passing 0 tells the operating system to assign any available ephemeral port. To test a specific port alongside diagnostics, combine the flags:

safaridriver -p 4444 --diagnose

If the driver successfully starts and listens on the new port, your previous session creation failures were likely caused by a local network port conflict.

Verifying Compatibility: --version

Session creation will fail immediately if there is a mismatch between your testing framework's expectations and the version of safaridriver installed on the machine. Unlike other browsers, safaridriver is bundled with the macOS operating system and updates alongside Safari.

Use the --version flag to output the exact version of the driver and WebKit:

safaridriver --version

You can use this output to verify that your WebDriver client bindings (such as Selenium or Appium) are compatible with the W3C WebDriver specification level supported by your current Safari installation.

Step-by-Step Diagnostic Workflow

To effectively use these flags to capture a session creation failure, follow this sequence:

  1. Open the macOS Terminal.
  2. Stop any currently running instances of Safari and safaridriver.
  3. Start the driver manually with diagnostics enabled: safaridriver -p 4444 --diagnose
  4. Configure your test runner to connect directly to http://localhost:4444 instead of launching the driver binary itself.
  5. Run the failing test to reproduce the session creation error.
  6. Press Ctrl + C in the Terminal to stop the driver.
  7. Navigate to ~/Library/Logs/com.apple.WebDriver/ and inspect the latest log file to identify the exact point of failure.