This document is intended to provide a troubleshooting methodology which incorporates publicly available utilities to diagnose and resolve an issue identified within a specific use case. The use case will be presented as a scenario where an IBM Cognos Support Analyst is working with a client to diagnose and solve a particular issue.
The utilities mentioned in this document can be found at,
Although the troubleshooting approach outlined is not IBM Cognos BI version specific, some of the diagnostic utilities used are. The version of the utility to be downloaded will be specific to the IBM Cognos BI version that is experiencing the issue.
Use Case Description
In this particular scenario, a Support Analyst is presented with a situation where a freshly installed IBM Cognos BI system fails to start for the first time. The client has configured all properties in IBM Cognos Configuration and saved the settings but when the Start button is clicked the start operation fails with an error message indicating a problem with the Content Store database connectivity.
Troubleshooting The Use Case
As with troubleshooting any use case, a set of basic information needs to be collected in order to further clarify the environment and the issue at hand. In this particular use case, the following information was provided by the client when logging the initial PMR with IBM Cognos Support.
- IBM Cognos BI version: 8.4.1
- Operating System: Windows 2003 SP2
- Java Runtime Environment (JRE): Sun, version unknown
- Content Store Database: Oracle, version unknown
Acquire Missing Information
Since the client is not sure which release of the Sun JRE is being used, the Support Analyst asks the client to start IBM Cognos Configuration and press Ctrl+F3. This brings up a dialog that displays information about the environment and installed version of IBM Cognos BI. This reveals that the version of the JRE being used is only 1.3. To the Support Analyst this raises a concern for two reasons.
First, this is a rather old version of Java and second, the client was unaware of the JRE version nor were they able to deduce the version on their own. This suggests that the client may be new to their IBM Cognos BI environment and since there is still important information missing about the Oracle client version and JDBC driver, the Support Analyst decides that it would be best to assist the client with gathering that information. The Support Analyst asks the client to download the IBM Cognos BI Health Check Diagnostic Tool located at the following URL,
This diagnostic tool gathers information about the installed software relevant to IBM Cognos BI and compares the identified software products and versions to the supported environment information for that particular release of IBM Cognos BI. The result will be a rating of compliant or not compliant for each of the considered software products.
As the Support Analyst already determined that the version of the Sun JRE is not supported, the client is advised to change the local environment so that it is making use of the JRE delivered as part of the IBM Cognos BI installation on Windows platforms, located in the ./bin/jre folder of the IBM Cognos BI install.
The next step is to run the diagnostic tool. The Support Analyst advises the client to check the options for Content Store, database support for reporting, Java runtime libraries, operating system and web servers. The other options don't apply to the client's IBM Cognos BI installation.
After the diagnostic tool has finishing running, it reports that the Content Store and the web server are not compliant. It turns out that the installed Oracle client version and JDBC driver used for the Content Store database access are not supported. The Support Analyst advises the client that they will need to upgrade their Oracle client to one of the versions listed as actively supported on the Supported Environments page at,
Additional Value Added
Since the Support Analyst included the web servers in the analysis, the client was also informed that their web server was not compliant and thus prevented a follow-up issue the client would have encountered after fixing the JDBC issue.
Dig deeper into Big data and analytics on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Tools, technologies, and software for building enterprise analytics solutions.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.