Learn How to Troubleshoot QuerySurge Execution API Issues
The QuerySurge Execution API (also called the QuerySurge CLI) is a powerful tool for automating QuerySurge tasks. However, depending on your system configuration and your environment, there are issues that you may encounter. This troubleshooting guide helps you work through common problems that you might encounter when you set up the API.
Issue 1: Empty log files / qsapi.properties credentials not encrypted
If any of the following events occur, a permissions problem is usually the cause:
- The auto-generated QuerySurge API log files remain blank or are not generated at all
- The credentials entered in the last line of the qsapi.properties are not encrypted as expected (after a first execution)
- The "java.io.FileNotFoundException: logFile.log (Access is denied)" error message appears in the logs (there will be considerable additional output, so you may have to search for this message)
This issue is usually due to a lack in write permissions for the Execution API user for the directory in which the API is installed - when you run the API under a user login, the API executes with your login's permissions - which often don't extend to the installation directory. (Other QuerySurge components run as services, which gives them access that the API may not have.)
In terms of options to resolve this, the first choice is privilege elevation for the current user - if the user can run under elevated privileges, the issue might be resolved (if user login privileges can be sufficiently elevated). However, often privilege elevation is not an option, so moving the installation folder to an accessible directory where the current user login is already privileged is an easy workaround. To do this, copy the cli folder from your QuerySurge installation directory to a directory your user has read-write access to (eg. C:\Users\myuser\Documents [Windows], or /home/myuser [Linux] directory). Then, edit your script to set the working directory to the new directory. Following are examples of edits - the first is a Windows example, where the cli/ directory is copied to C:\Users\myuser\Documents\cli, and the second is a Linux example, where the cli/ directory is copied to /home/myuser/cli:
Issue 2: "Connection Refused"
The "Connection Refused" error message can be triggered by a number of configuration issues or circumstances.
1. Incorrect host name or port
A common configuration mistake that causes the "Connection Refused" error message is the use of an incorrect host name or port. This typically happens after the migration of a QuerySurge instance and the host name and ports have not been changed within the scripts running Execution API commands.
2. Ports are closed / blocked
Typically, QuerySurge instances are setup behind internal and/or external software firewalls. If any firewalls are blocking the QuerySurge App server, a "Connection Reused" error message is returned. Assuming that your QuerySurge instance is available, check with your network administrator about whether there are any firewalls that may be interrupting connectivity between your QuerySurge API and the QuerySurge App server.
3. QuerySurge is Down
More often than not, the "Connection Refused" error message will be due to a missing QuerySurge instance. The Execution Library cannot interface with QuerySurge without a running application server. Check with our QuerySurge administrator to ensure that QuerySurge is operational, connected to the network, etc.
Issue 3: "java.lang.reflect.InvocationTargetException"
When you execute scenarios via the Execution API, one option is to pass only your QuerySurge username in the API function call, and to enter your credentials in the qsapi.properties file. If these credentials do not match that of the QuerySurge instance in question, an InvocationTargetException is returned. To fix this issue, enter your credentials, separated by an equals (=) sign, in the qsapi.properties file:
In this example, the QuerySurge username is 'admin' and the password is 'admin'. Note that, after the first Execution API run using these credentials, the credentials are encrypted in the file. The API works this way so that there are no plain-text QuerySurge credentials in the file.