MicroStrategy ONE

Troubleshooting Your MicroStrategy Library Installation

Issue: My Library is Empty

  1. Open the Library Administration Control Panel and check that Intelligence server is configured and running.
  2. No content has been added to your Library.
  3. Monitor REST API error

    When the Library Web application behaves unexpectedly without any error message, monitor the error messages being returned from the MicroStrategy REST API using the web browser debugging tool.

    1. From Chrome, open Developer Tools.
    2. Open the Network tab.
    3. Perform the steps to reproduce.
    4. Check that all of the requests are captured.
    5. Click a network request that you are interested in.
    6. Within the request info window, open the Preview tab. This will display the response in JSON format.
    7. Look for any network requests that are red, as this indicates that the REST API request may have failed. If you are looking for API errors only, click the XHR option so that the network tab displays all http(s) calls including the APIs.
  4. Review the MicroStrategyLibrary error logs and look for any console errors in the browser debugging tool.
  5. Ensure you have the Use Library privilege for all projects (see Privileges in Library Web), so you can access dashboards within all projects.

Issue: Collaboration Server is Unavailable

  1. If the Notification Icon is not available:

  2. If the Notification Icon is available but disabled, the Collaboration server is not connected. Click the icon and use the error message dialog to contact your administrator.
  3. Monitor Web Socket error

    When Collaboration server features within the Library fail without a detailed error message, monitor the error message directly from Web Socket messages using the web browser debugging tool.

    1. From Chrome, open Developer Tools.
    2. Open network tab.
    3. Perform the steps to reproduce.
    4. Filter the request type by "WS" (WebSockets).
    5. Click on a network request.
    6. Within the request info window, open the Frames tab. This will display the requests and responses in JSON format.
    • If you don't see any request, refresh the page. It is possible that the browser debugging tool started capturing network calls after the Web Socket connection is established.
    • If you don't see any requests even after refreshing, the communication between the Library Web and Collaboration server in your environment is through HTTP polling instead of a Web Socket due to an environment limitation.

Common Configuration Errors

  • Error indicating that the connection is refused, such as:
    • Unable to invoke Authentication Server Method. Error: connect ECONNREFUSED 127.0.0.1:8443 (code=ECONNREFUSED) Unable to connect to the Authentication Server.
    • Verify that the "authorizationServerUrl" uses the same machine name as the "Common Name" associated with your certificate. In short, you cannot open a secure connection to a machine if you don't have the certificate for that same machine and the certificate is not signed by a trusted certificate authority.
  • Error indicating a problem with the certificate, such as:
    • Unable to invoke Authentication Server method. Error: unable to verify the first certificate <code=UNABLE_TO_VERIFY_LEAF_SIGNATURE>. Unable to connect to the Authentication Server.
    • Verify that the certificates specified in the Collaboration server config.json file are the same used to create the keystore file used with Tomcat.

Diagnose Collaboration Server Connection Issues

MicroStrategy installations provide a command line diagnostic tool for troubleshooting Collaboration server connection issues.

To invoke diagnostic tool:

Windows:

Change the current working directory to <MicroStrategy_commonFiles_path>\nodejs.

Run the command:

Copy 
node "<MicroStrategy_installed_path>\Collaboration Server\node_modules\mstr-collab-svc\diagnose.js" "<MicroStrategy_installed_path>\Collaboration Server\config.json"

Linux:

Run the following command from the /opt/mstr/MicroStrategy/install/CollaborationServer directory to launch the Collaboration server's diagnostic tool:

Copy 
./collaborationServer.sh diagnose

Invoking the diagnostic tool on a running system will return the following:

  • Both dependent servers will show as Connected

  • Collaboration server shows as Started and in a running state.

  • A list of trusted certificates with the name and expiration date (only if trusted certificates are set in config.json file)

Common Errors from the Diagnostic Tool

Collaboration Server Shows as Stopped

This means the Collaboration server is not running. You need to start the Collaboration server and re-run the diagnostic tool.

Trusted CA Certificate Files

The diagonistic tool will try to read each file path configured in config.json file as a trustedCert. There may be multiple certificates in a single file. Here are the possible results:

  • Success

  • Un-supported format

  • Warning: Contains an expired certificate

  • Invalid PEM block

  • Success: 2 certificates

  • Warning: Contains an expired certificate (There are 2 certificates inside this file. One is valid and one is expired)

Troubleshooting through Collaboration Server Logging

If Collaboration server logging is enabled, the logs created by Collaboration server will provide more detailed information including:

  • Running warnings and errors
  • Request activities
  • Notification records

Library Server to Collaboration Server Errors and Warnings

Warning: Secret Keys Do Not Match

Library server and Collaboration server need to be set up with the same secret key (a string with a minimum of 5 characters) in order to verify the other server's identity. If the secret keys do not match, the Library server cannot talk to the Collaboration server. Functionality such as updating the Collaboration server configuration in Library Admin control panel will fail. The Library server itself is okay to use.

Warning: Truststore is missing in Library Server

If the Collaboration server is running with TLS enabled and is using a private root CA signed certificate, the Library server is required to present the corresponding certificate in order to establish a secure communication. The administrator can configure a truststore file in the Library server (see MicroStrategy Library Server Configuration Properties). Failure to reference the required certificate in the truststore will lead to this warning. With this warning active, the Library server cannot communicate with the Collaboration server. Functionality such as updating the Collaboration server configuration in Library Admin control panel will fail. The Library server itself is okay to use.

Warning: Cannot establish socket connection from browser to Collaboration server

In some cases, the Library server can talk to the Collaboration server but end users (browsers) may fail to establish communication to the Collaboration server (failure to establish a socket connection). There are three possible causes:

  • The Library server is running with TLS enabled (URL starting with 'https') while the Collaboration server is running with TLS disabled (URL starting with 'http'). Some browsers will block any request to 'http' if the current website is using 'https'.

  • The Collaboration server is running with TLS enabled but using a private root CA signed certificate. Some browsers will consider such private root CAs as untrusted and block requests to those servers. The administrator may need to add those private root CAs into the trust list.

  • The administrator may use a hostname like 'localhost' as the machine name for the Collaboration server in the Library server. That hostname is only recognized by the Library server and not accessible from other users (client machine/browsers).

    There may be two causes:

    • Cannot find IP address for that hostname: end user can update the hosts file in system which can help system to resolve domain names to an IP address

    • The IP address is not visible to end user: It may be a local ip address or the port is not exposed to public.

Collaboration Server to Library Server Errors and Warnings

Warning: The Collaboration Server is Not Targeted at the Current Library Server.

This is only a warning: the Collaboration server is talking to a different Library server. The current Library server is okay to use. Potential issues may occur when the two Library servers provide different data.

Error: The Collaboration Server is Not Targeted at the Current Library Server and the Target Library Server is Not Reachable.

For this case, the collaboration-related features in Library are not usable since the Collaboration server is paused due to this error. The administrator may choose to use the current Library server as the target Library server for this Collaboration server.

Error: Target Library Server is Not Reachable and Cannot be Set Up through Administration Control Panel

There are two cases when Admin UI can display issues about the current Collaboration server but cannot provide any solutions for the problem:

  • Secret keys do not match between the Library server and Collaboration server.

  • The Collaboration server is TLS enabled using a private root CA signed certificate while the Library server is missing the truststore for that certificate.

Both causes will lead to the Library server being unable to communicate with the Collaboration server and thus unable to control/update Collaboration server settings.

Error: The Collaboration Store is Not Reachable

The current Administration control panel does not expose an interface to update the Collaboration Store. The administrator can manually update it through the Collaboration server configuration.

Library Server to Intelligence Server Errors and Warnings

Error: Intelligence Server is Not Reachable

The administrator will see this error message when the Library server is unable to connect to the current Intelligence server.

The administrator will see this error message when the Library server is unable to connect to the current Intelligence server and Admin UI has succeeded in a connection test using the hostname and port of the current Intelligence server. This is most likely caused by using an incorrect TLS setting.

Error: Minimum Version Requirement

If the Library server has set a minimum Intelligence server version requirement and the current Intelligence server doesn't meet that requirement, this error message will be displayed.