Troubleshooting QuerySurge Base CLI Issues

Versions: 8.0+

Learn How to Troubleshoot QuerySurge Base API Issues

The QuerySurge Base API is a lightweight execution API, which allows users to drive QuerySurge execution from an external command line or scripting environment. 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.

 Note: The QuerySurge Base API is part of the core QuerySurge release and requires no additional licensing. The QuerySurge DevOps API is licensed separately. The Test Management Tool Connector API is also licensed separately. To arrange for licensing, contact [e-mail] or your QuerySurge Business Development representative.

Issue 1: After Upgrade to version 8.0+, Scripts Fail to Execute

If you have recently upgraded to QuerySurge 8.0+, your API scripts will fail with the following error:

An error occurred while running command: <command-name>
[com.rttsweb.querysurge.cli.exceptions.QuerySurgeCliException: Project Id not found on command or in properties file. Please add project id to continue]

You'll need to modify your API setup to reference a Project ID. See this article for more information.

Issue 2: 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 Base 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:

qscli.bat (Windows):

cd "C:\Users\myuser\Documents\cli"
...

qscli.sh (Linux):

cd "/home/myuser/cli"
...

Issue 3: "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 Base 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 an inaccessible QuerySurge instance. The API 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 4: "java.lang.reflect.InvocationTargetException"

When you execute scenarios via the Base 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:

     e.g: admin=admin

In this example, the QuerySurge username is 'admin' and the password is 'admin'. Note that, after the first Base API run using these credentials, the credentials are encrypted in the file. The API works this way to offer an option to avoid QuerySurge credentials in the file in plain-text .

Issue 5: Windows Powershell Scripts fail to execute

If you are scripting your API calls in Windows Powershell, note that the default Powershell execution policy is Restricted. This means that Powershell cannot execute unless specific conditions are met. See this article for general information as well as options for Powershell execution. Note that your organization may have policies governing script execution.