Troubleshooting

This page provides some common troubleshooting tips. Many topics on this page require advanced knowledge. For more information or assistance, talk to your Genesys representative, and see the links at the bottom of this page.

Important

In keeping with Genesys' commitment to diversity, equality, and inclusivity, beginning with release 9.0.019.01, some pod names are changed; this document refers to "gcxi-primary" and "gcxi-secondary" pods. In release 9.0.019.00 and earlier, these pods were named "gcxi-master" and "gcxi-slave".

Container startup logic

This section describes the general logic of GCXI startup. Understanding this process can help you to troubleshoot problems.

About gcxi-init

You execute this job when GCXI is first installed, at which time it:

creates GCXI service objects in the specified database server: meta / history databases and logins.
loads gcxi data (initial Projects) into newly created databases.

Once gcxi-init completes, we expect that the Microstrategy metadata database (the "meta db") has been created. You can perform the following actions to verify that this is the case:

Check the gcxi-init logs to ensure that the Microstrategy metadata database has been created without error.
Check DB Server to ensure that the meta database is available.

Main gcxi container startup

Each time the gcxi container starts, it:

Checks the environment variables and default values to determine the MicroStrategy Administrator password, and optionally changes the password.
Starts MicroStrategy server inside the container (a valid meta db is required for MicroStrategy to start properly).
If you encounter a problem at this stage, check the following:
- if MSTR server fails to start immediately, ensure that the meta db is available.
- if MSTR server fails to start after a delay of about 3 minutes, and exits with the error Failed to start MSTR server!, check sysctls / shared memory settings on the host.
Runs Command Manager (a Microstrategy client tool) using the MicroStrategy Administrator account and password, and executes the following commands in Command Manager:
```
LIST ALL DBLOGINS;
```
```
LIST ALL DBCONNECTIONS;
```
```
LIST ALL DBINSTANCES;
```
If these commands fail, ensure that Command Manager is able to log in to the MicroStrategy server (ensure that a valid MicroStrategy Administrator password was provided in step 1).
Creates DSNs (MicroStrategy connectivity objects), which are used to connect to Genesys Info Mart and other data sources. The DSNs are created based on the container DSNDEF* environment variable.
If the value of the environment variable GCXI_VERSION is later than the current GCXI release number, an upgrade procedure starts. This one-time task can take up to 30 minutes to complete.
Performs other MicroStrategy server configurations (some are executed only by a PRIMARY container).
Configures and starts Tomcat.

Out of Memory error in log when docker-compose -f docker-compose.yml up is executed on Windows

When starting GCXI on Windows, an error can appear if there is not sufficient memory configured for the virtual machine. Resolve this as follows:

Open Hyper-V Manager.
Open the Settings of your virtual machine, and navigate to the section Hardware > Memory.
Select the option Enable Dynamic Memory.
In the Windows system tray, access the Docker context menu, and open Settings of Docker Desktop “Settings”.
In the section Resources > Advanced, increase the allocated memory, and save your changes.

Port error when compose runs on Windows

The following error can appear when you start Docker under Windows:

>docker-compose -f docker-compose.yml up
<…>
ERROR: for gcxi-0  Cannot start service gcxi-0: Ports are not available: listen tcp 0.0.0.0:8080: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
ERROR: Encountered errors while bringing up the project.

This indicates that the port 8080 is in use. To resolve this issue:

Open the docker-compose.yml file for editing.
Change the port mapping as follows: edit the line 8080:8080, changing the first value to <unused_ port_in_windows>:8080”, where <unused_ port_in_windows> is an unused port, for example 8280:8080. If you remap this port, be sure to use the new port value when accessing MicroStrategy web interface.

Could not translate host name "gcxi-postgres" to address: Name or service not known

In some scenarios, an error can appear when you create the MicroStrategy meta database, similar to the following:

++ psql --host gcxi-postgres --port 5432 --username postgres --dbname postgres -tAc 'SELECT 1'
psql: could not translate host name "gcxi-postgres" to address: Name or service not known
++ '[' 2 -eq 0 ']'
++ code=1
++ echo 'Connection to meta db server failed. Either wrong admin creds provided, or DB is broken.'

To work around this issue:

Open the gcxi-init.yaml file for editing, and find this line:

command: [ "/bin/sh", "-c", " ${GCXI_INSTALL_HOME}/run_init.sh" ]

Edit it to read:

command: [ "/bin/sh", "-c", "echo '<GCXIpostgresIP> gcxi-postgres' >> /etc/hosts && ${GCXI_INSTALL_HOME}/run_init.sh" ]

Where <GCXIpostgresIP> is the IP address of the gcxi-postgres pod, for example:

command: [ "/bin/sh", "-c", "echo '10.244.0.4 gcxi-postgres' >> /etc/hosts && ${GCXI_INSTALL_HOME}/run_init.sh" ]

Try again to create the MicroStrategy meta database.

Genesys CX Insights fails after restart

If Genesys CX Insights fails after restarting, one possible cause is a missing/disabled Project, which prevents the GCXI container from starting. Check to ensure that required Projects in the meta database are not in a disabled state:

Open MicroStrategy Developer.
Right-click the server name, and select Configure MicroStrategy Intelligence Server.
In the Project > General section, ensure that check boxes are selected next to required Project names.

Container Diagnostics

If the GCXI container fails on startup, and the reason for the failure is not immediately evident, Genesys recommends that you set the following debugging variables, and re-run the GCXI main container:

DEV_XTRACE_LEVEL=ALL
This provides super-extended logging, which is helpful in many scenarios.

Warning
Warning: all passwords are visible in container logs. Genesys recommends that you do not share this log with Customer Care, or any other party, unless you have first removed all sensitive information, such as passwords, from the log file.
DEV_ERR_EXIT=false
This provides more information in scenarios where the container does not exit on error and continues to run.

Generating logs

If you need assistance from Genesys, you may be asked to provide logging output. At a minimum, provide the logs, saving each output to a separate file with a name that clearly identifies each one. Note that this example is for Kubernetes; if you use a container engine other than Docker, use corresponding commands for that engine:

## general docker and k8s inspection
kubectl version
docker version
docker info
docker images
service docker status
 
## kubernetes objects
 # please provide the FULL log
kubectl log <gcxi_primary_pod>
kubectl get pod --all-namespaces -o wide
kubectl get node -o wide
kubectl get events --all-namespaces
kubectl get job -o wide
 
kubectl get cm gcxi-config -o yaml
kubectl get job gcxi-init -o yaml
kubectl get deploy gcxi-primary -o yaml
kubectl get pod <gcxi_primary_pod> -o yaml
 
# is containerized postgres used
kubectl log <gcxi_postgres_pod>
kubectl get pod <gcxi_postgres_pod> -o yaml
 
# if gcxi-init job instance still exists
kubectl log <gcxi_init_pod>
kubectl get pod <gcxi_init_pod> -o yaml
 
## linux info
hostnamectl
free -h
df -h
sestatus
 
## sysctls
sysctl kernel.sem
sysctl net.bridge
sysctl vm

Kubernetes Inspection

If you suspect that Kubertnetes might be the source of a problem, see the document https://learnk8s.io/troubleshooting-deployments, which provides a troubleshooting flow-chart to guide you through troubleshooting Kubernetes in your deployment.

MicroStrategy resources

This section provides links that are useful when you are performing troubleshooting. The URLs in the following table point to the latest page on the MicroStrategy documentation site. If the documentation page that loads is more recent than your installed release, you can modify the URL by replacing Current with a specific release number.

Topic	URL
What's New	https://www2.microstrategy.com/producthelp/Current/Readme/en-us/Content/whats_new.htm
System Settings / IPC Requirements	https://www2.microstrategy.com/producthelp/Current/InstallConfig/en-us/Content/Software_requirements_and_recommendations.htm
Advanced Reporting Guide	https://www2.microstrategy.com/producthelp/Current/AdvancedReportingGuide/WebHelp/Lang_1033/Content/home.htm
MSTR Web Guide	https://www2.microstrategy.com/producthelp/current/MSTRWeb/WebHelp/Lang_1033/Content/home_mstrweb.htm
MSTR Supported Configurations	https://www2.microstrategy.com/producthelp/Current/Readme/en-us/Content/certified_configurations.htm Click View Dossier to learn more about certified product releases.
Search for other topics	You can easily search for detailed information about MicroStrategy products: On the MicroStrategy Community Search Page, enter your search terms. Filter your search results by selecting the Document Version (such as 2020).

Contents