The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. See what DNS servers and SSL certificates can be found in your network when Sauce Connect Proxy boots up.
  2. Verify that the Sauce Connect 4.5.1 and lower: Sauce Connect Proxy needs to make outbound connections to Proxy tunnel can make connections to and  and * on port 443 for the REST API and the primary tunnel connection to the Sauce cloud.
    Sauce Connect 4.5.2 and higher: Sauce Connect Proxy needs to make outbound connections to and th IP ranges listed below on port 443 for the REST API and the primary tunnel connection to the Sauce cloud on port 443 using the DNS servers found in your network.
  3. Verify that the Sauce Connect Proxy tunnel can make connections on port 443 and 80 to and using the SSL certificates found in your network.
  4. Verify that you are able to make a connection to these Sauce Labs REST API calls:[Your Sauce Username]/tunnels
  5. Verify that the Sauce Connect can make a connection to

If you need additional assistance when tests are failing with Sauce Connect Proxy, get in touch with our support team at When creating your support ticket, please remember to send us the doctor flag, the link to your Sauce Labs test, and the Sauce Connect verbose log. You can get the verbose log by adding the -vv and -l sc.log options to your Sauce Connect Proxy command line:

sc -u [Your Sauce Username] -k [Your Sauce Access Key] -vv -l sc.log

--doctor Errors


failed to fetch PAC file ...: ...

Indicates the specified PAC file couldn't be downloaded. This may be caused by an incorrect URL, or a network mis-configuration. To troubleshoot this type of issue, try to download the PAC file manually from the machine running Sauce Connect with Curl or another HTTP client.

To debug the PAC file you can create one locally and pass it to Sauce Connect Proxy using the --pac option like this:

Code Block
$ sc --pac file:///path/to/pacfile.js

In Windows, remember to add the drive to the path like this:

Code Block
$ sc --pac file://C:/path/to/pacfile.js
failed to fetch or empty PAC file ...The connection to the remote server was successfull but the PAC file was empty or missing.

both --proxy and --pac are used

Using both may work, but this is unsupported by Sauce Labs and should only be used if directed by the Saucelabs support.

invalid REST URL ...

The URL specified in the -x option is invalid.

failed to find proxy via PAC for ...

The PAC file was downloaded successfully, but no proxy was found for this host. This may be the result of an incorrect PAC file: make sure a proxy is specified for all the hosts.

can't resolve ''/... tunnel hostname(s) via any DNS server

Please check your firewall and DNS settings.

To troubleshoot this issue, use dig or host to resolve the domain and verify it is correct:

Code Block
$ dig

your hosts file contains an entry for ...

The DNS server can't resolve correctly, this is most likely because the DNS system has a special configuration for some hosts. We strongly recommend you remove this entry from the host file: it's usually /etc/hosts on Unix-like systems. With Linux/Mac OS X systems, you can check the hosts file with this command.

Code Block
$ grep '' /etc/hosts

connecting via <proxy> to http://<url>: <error> or connecting to http://<url>: <error>

The URL isn't accessible. If you see this error after other errors in the logs, try to fix the previous errors first.

Please refer to the libcurl errors manual to troubleshoot this issue.

SSL connect failed, socket: ... code: %d

The Secure connection couldn't be established. Please refer to the OpenSSL manual to get more information about the error.

failed to retrieve certificate chain

Some X509 certificates couldn't be imported into the SSL library. This may indicate an issue in with DNS, or public CA's being unreachable.

failed to reach https?://

The Sauce Connect client can't reach, this indicates that the client doesn't have full Internet connectivity. It may not be an issue: Sauce Connect only needs access to and its tunnels.