Troubleshooting the Cognos® BI Server

If you encounter problems when you deploy or configure the HCL Cognos® BI Server component or when you use the Metrics application, use this information to help resolve the problem.

Potential Cognos® problems and solutions

Table 1 lists problems you might encounter with the Cognos® BI Server component and suggests solutions.

Table 1. Potential problems with the Cognos® BI Server component and suggested solutions

Column 1 describes problems that you might encounter with Cognos® BI Server, and column 2 suggests how you can resolve them.

Problem Solution

JDBC connection error occurs while it runs the cognos-setup.bat|sh script to install BI Server:

Performing validation check ...
JAR file(s) found in JDBC driver directory:
Using cognos.locale: EN 
All properties provided for Cognos database 
All properties provided for Metrics database 
Failed to verify the JDBC connection to Cognos Content Store database. Please check the error message.

Make sure the database server is configured to accept remote connections; consult the vendor documentation for your database product. In particular, Microsoft SQL Server does not accept remote connections by default and must be specifically enabled before you can install Cognos® BI Server. For information on enabling remote connections for SQL Server, see the archived blog entry How to enable remote connections in SQL Server 2008? at the Microsoft site.

After SQL Server has been correctly configured, run the cognos-setup.bat|sh script again.

Cognos® BI Server cannot be installed successfully on SUSE Linux and the following errors occur:

  1. The log displays the following error while it loads shared libraries:
    Error while loading shared libraries: cannot open shared object file: No such file or directory.
  2. There are no Cognos® folders in the Cognos® installation directory.
  3. In the WebSphere® Application Server's Integrated Solutions Console, there is no Cognos® EAR file listed in the applications table.

This problem indicates that required patches were not installed before attempting to deploy Cognos®.

Correct the problem with the following steps:
  1. Determine whether a patch was installed by running the following command:
    $ rpm –qa | grep <rpm package name>
  2. To install the patch:
    $ rpm -i <rpm package name>
  3. To upgrade the patch:
    $rpm -U <rpm package name>

Cognos® BI Server will not start.

Check the value in the WebSphere® server log SystemOut.log to see if it matches the Cognos® BI Server installation path. If the installed path is different (for example, you moved the files or renamed the directory), you can update the Cognos® BI application file to reference the correct path. For instructions, see Manually changing the installation directory name affects installations running under an application server in the Cognos® information center.

You need to stop (or restart) Cognos® BI Server.

Whenever you need to stop (or restart) Cognos® BI Server, you must additionally stop the IBM® WebSphere® Application Server where Cognos® is hosted. For best results, follow these steps:
  1. Stop the WebSphere® Application Server hosting the Cognos® server.
  2. Wait at least 1 full minute to ensure that all of the Cognos® processes have completely stopped:
    • HCL AIX® or Linux: and CAM_LPSvrprocesses
    • Microsoft Windows: cgsLauncher.exe and CAM_LPSvrprocesses
  3. Start the WebSphere® Application Server.
  4. Start the Cognos® server.

When adding users or groups to the IBMConnectionsMetricsAdmin security role, you find the names that are tagged as folders instead of as users, and you cannot add them to the security role.

This indicates that users are mapped to the same object class as folders in the LDAP, and Cognos® cannot differentiate between them, so it is treating users as folders. Correct this problem using the following steps to run the Cognos® Configuration Tool and modify the object class mappings in the IBMConnections namespace.
  1. Consult your LDAP administrator to determine the object classes that should be used in your deployment.
  2. Navigate to the /bin64 subdirectory of the Cognos® BI Server installation directory.
    For example:
    • AIX® or Linux: /opt/IBM/CognosBI/bin64/
    • Windows: C:\Program Files\IBM\Cognos\bin64
  3. Start the Cognos® Configuration tool by running the following command:
    • AIX® or Linux: ./
    • Windows: cogconfigw.exe
  4. Expand Local Configuration > Security > Authentication.
  5. Edit the Connections namespace and set the object class for Folder mappings to a different value than the object class used for in Group mappings and Account mappings.
  6. Click File > Save.
  7. Exit the Cognos® Configuration tool, making sure to select No at the following prompt:The service 'Cognos' is not running on the local computer. Before you can use it your computer must start the service. Do you want to start this service before exiting?
  8. Stop the IBM®WebSphere® Application Server that hosts the Cognos® server.
    Wait at least 1 full minute to ensure that all Cognos® processes have stopped:
    • AIX® or Linux: and CAM_LPSvr processes
    • Windows: cgsLauncher.exe and CAM_LPSvr processes
  9. Start WebSphere® Application Server.
  10. Start the Cognos® server.

The Cognos® Content Store database is available but you cannot access the following URL:

http://Cognos WAS server host name:port/Cognos_context_root/servlet
There are several different potential causes for this error message:
  • Verify that the context root value specified for the Cognos® application in WebSphere® Application Server matches the value specified in the cognos.contextroot setting of the file.
    1. Log into the Integrated Solutions Console as the WebSphere® administrator.
    2. In the navigation tree, click Enterprise Applications > Cognos_application_name.
    3. In the list of applications, check the value in the Context Root For Web Modules field and update it if necessary to match the setting used in the properties file.
    4. Click Apply, and then click OK.
    5. Save the change to the master configuration by clicking Save in the "Messages" box.
  • Verify that the Cognos® Content Store database is available and accessible (check the Cognos® BI Server system log for database connection errors.
  • If you are using HCL DB2®, verify that the maximum number of concurrent databases is large enough for your deployment (this value should be set to a value greater than 15).

The Cognos® BI Server is available but you cannot access the following URL:

This problem can indicate that the Cognos® Content Store database is not available or that the BI Server’s Dispatch settings are incorrect.
  1. Verify that the Cognos® Content Store database is available.
  2. Use the Cognos Configuration tool to verify that the following settings in the Cognos® BI configuration specify the correct host name and port for the BI Server:
    • Dispatcher URIs for gateway
    • External dispatcher URI
    • Internal dispatcher URI
    • Dispatcher URI for external applications
    • Content Manager URIs

Unable to log in to the Cognos® BI Server using the following URL after setting up authentication and disabling anonymous access:


This might indicate a problem with the namespace configuration. Verify that the IBMConnections namespace is configured correctly with the authentication provider.

Note: The namespace is specified by the cognos.namespace property in the file; IBMConnections is the default value.

Verification failed when accessing the following URL:


The following message is displayed:

CAM-AAA-0135 The user is already authenticated in all available namespaces
There are many different potential causes for this error message, but the most likely problem is incorrect Dispatcher settings for the Cognos® BI Server.
  1. Use the Cognos Configuration tool to verify that the Dispatcher URIs for gateway setting in the Cognos® BI configuration specifies the correct host name and port for the BI Server.
  2. If you still cannot access the URL, refer to the following IBM® technote for additional information: .**Troubleshooting** error message when logging into Controller CAM-AAA-0135 The user is already authenticated

The following error message is displayed in the window that opens when you click the Help link in the product header: logServletError SRVE0293E: [Servlet Error]-[CMServlet]: Access denied (java.lang.RuntimePermission createClassLoader)
This message indicates a security issue where user verification has failed. You can resolve this problem by disabling Java 2 security on the Deployment Manager with the following steps:
  1. Log into the Integrated Solutions Console as the WebSphere® administrator.
  2. Click Security > Global Security.
  3. Look under "Java 2 security" and clear the selection for Use Java 2 security to restrict application access to local resources.
  4. Click Apply, and then click OK.
  5. Save the change to the master configuration by clicking Save in the "Messages" box.

Build all data fails when running ./

In trxschelog.log
UDA-SQL-0569 Unable to load the driver manager  library(
UDA-SQL-0571 The operating system returned an error message(./ version 'NSSRAWHASH_3.12.3' not found (required by /lib/ processing 0 records from date source
'D_SOURCE~1'.(TR3703) The user ID or password is either missing or invalid. Please re-enter the credentials.

Run the following command to preload the libraries needed: export LD_PRELOAD=/usr/lib/

After running ./, /opt/IBM/Cognos/bin is a file, not a directory.

Uninstall Cognos and run ./ again.

During the Cognos installation, after running the cognos-configure.bat|sh script, the following exception occurs in the cognos-configure.log and the installation fails:

Err, Unable to save the configuration file.
The parameter named 'External dispatcher URI' located in 'Environment' is currently invalid.

Check the cognos.contextroot value in the file. If the value includes a forward slash (/), choose another context root without a forward slash since Cognos does not support a context root that includes (/).

  1. Replace the cognos.contextroot value with 'cognos' or another single word in the file.
  2. Update the context root in WAS with the new value for the Cognos application.
  3. Restart the Cognos server.
  4. Rerun cognos-configure.bat|sh.