Fixing “Failed to communicate with the built in Jetty Server” Errors

This article describes how to fix SQLForce’s “Failed to communicate with the built in Jetty Server” error.

If you have just installed over an exsiting version of SQLForce and see this problem:

  • Uninstall SQLForce.
  • Reinstall SQLForce.

This will clear up a problem caused by overwriting SQLForce’s internal version of Jetty with a new version.

How Does SQLForce Work?

The first time a request is made using SQLForce, a local lightweight web application server is launched on the local computer. The SQLForce Python code uses a REST interface on this application server any time it interacts with Salesforce. The web services hosted by the application server use the Salesforce API to communicate with Salesforce using the same robust libraries used by CopyStorm. When the Python program exits the web application server is automatically shutdown.

When a “Failed to communicate with the built in Jetty Server” appears in Python this usually means that the web server was started but is being blocked from accepting requests on the port allocated by the Python code. Note that the allocated port changes each time the web server is launched and uses port ranges that are generally public and unrestricted.

Jetty is the name of the technology implementing the web application server.

Test 1: Verify That Java 1.8 or Above is Installed.

SQLForce requires Java 1.8 or higher. You can tell which version of Java is installed on your system by running the command:

  • java -version

If any version lower than 1.8 is returned you must install an updated Java on your computer prior to using SQLForce.

Test 2: Verify That Jetty Can Start and Accept Requests.

This section explains how to start Jetty by hand and verify that it is accepting requests. When going through the steps in this section an error message will often appear indicating a firewall (or other resource) protection problem.

  • Change to the directory where the SQLForce Python extension was installed.
    • On Windows: PythonRoot/Lib/site-packages/SQLForce
    • On Linux: /usr/local/lib/python3.3/site-packages/SQLForce
  • Change to the “jetty” sub-directory.
  • Start Jetty with the following command line:
    • java -jar start.jar jetty.port=8888
    • If you see a lot of messages about failing to parse modules then you need to reinstall SQLForce. This can happen when installing a new version of SQLForce on top of an existing version.
  • Open a browser and enter the following URL to establish a connection to Salesforce, using the second line when connecting to a custom endpoint:
    • http://localhost:8888/SQLForce/Connect?command=CONNECT PRODUCTION mysalesforcePassword
    • http://localhost:8888/SQLForce/Connect?command=CONNECT PRODUCTION mysalesforcePassword
  • If successful, Jetty will respond with a message like:
    • {“sessionKey”:”1ihy9njxbdzta5v8yp0l9zync”,”successful”:true}
  • Run a SELECT statement against Salesforce by entering a URL like the following into your browser. Note the use of the session key created in the previous step:
    • http://localhost:8888/SQLForce/Select?soql=SELECT%20name%20FROM%20User&sessionKey=1ihy9njxbdzta5v8yp0l9zync

Test 3: Firewalls and Startup Delay.

If the previous tests passed there are two remaining issues likely causing the problem:

  1. Your firewall is blocking Python from communicating with the network. To fix this problem update your firewall configuration or, for the short term, disable your firewall.
  2. Your computer is taking too long to start up the Jetty process.

When SQLForce starts the Jetty process it gives the operating system a short amount of time to finish Jetty initialization prior to issuing a request. On a slower computer the default delay may be too short, to increase the delay:

  • Find SQLForce in the site-packages directory of your Python install.
  • Open the file in a text editor.
  • Look for the variable StartupDelay and increase its value. The default value is 2 seconds.
  • Retry the failing Python script.

Last Chance: Email Support.

If SQLForce is still failing to find Jetty send an email to We will be glad to help you.