Issues most commonly encountered during an upgrade (Jama 2015.5 and earlier)

By Elden posted 11-23-2015 04:34


If you encounter issues with Jama 2015.5 and earlier while performing an upgrade, please feel free to reach out to Jama Support for assistance with troubleshooting. If you are the type of person who likes to try to figure things out for themselves, this article contains some common issues you might encounter during an upgrade and what things to look at to help resolve the issue. The information found here is some of the same information Jama Support will use when assisting you. 

This article assumes that you have read and are familiar with the contents of the following articles:

Issues During the Upgrade
Tomcat does not load
The first thing to determine is whether Tomcat is up and running. Normally when you try to navigate to the Jama home page, you enter a URL like http://my.tomcat.server:8080/contour.

  • Try navigating to the same URL minus the /contour. If Tomcat is running, you should get to the Tomcat homepage. 


  • If you cannot get to the Tomcat homepage, make sure Tomcat is started and verify your Tomcat configuration. Tomcat support falls outside the scope of Jama support but you can refer to the Apache Tomcat documentation for additional information. Also, refer to our production system requirements page in the User Guide and verify you have configured your Java memory settings correctly.
  • Make sure you have not accidentally run Tomcat more than once. If you have multiple instances of Tomcat running, you will want to shut them all down, clear the cache and launch one new instance of Tomcat. To clear the cache:
  1. Stop Tomcat. (You should have already done this.)
  2. Navigate to your contour_home directory.
  3. Delete the activeMQData and temp directories.
  4. Navigate to tomcat_home.
  5. Delete the contents (but not the actual folder) of work and temp.
  6. Start Tomcat.

Jama does not load
If you can navigate to the Tomcat home page but are unable to get to Jama after adding /contour to the URL, the problem may be a variety of things. The type of symptom/error you are seeing will help determine the next steps in troubleshooting.

  • If you are using Windows, make sure when you unzipped Jama you allowed the unzip process to complete. We have seen situations while using the built-in Windows unzipping tool where files can become corrupt if you click 'next' prior to the completion of the unzipping process. Try unzipping and installing Jama again.
  • When you installed Jama, did you delete the existing contour folder or did you copy and replace? It is best practice to remove* the old contour folder and replace it with the new one. Copying into the existing contour directory may have unexpected results.
  • 404 Error - There are two primary reasons you might receive a 404 error: 
    • For the most current on-premises version of Jama, refer to our supported software and environments article to determine what version(s) of Java are compatible.
    • If you are using a previous but supported version of Jama (we officially support versions dating 12 months prior to the latest release,) refer to the "Installation" section in the pertinent user guide.
    • If you are using a version of Jama older than 12 months and/or are performing an incremental upgrade, contact [Jama Support] for copies of the older user guides.
    • You are using the wrong version of Java.
    • You are using an incorrect URL. Double check the path to Jama. Navigate to [tomcat_home]/webapps/ on your server. Do you see a folder named contour? Has the folder been renamed to something else? If yes, you need to specify that folder name in place of /contour.
  • 503 Error - If you are receiving a 503 error, you are likely using the correct URL and something else is the issue.
    • Look in the contour.log file. You can find that file in [tomcat_home]/logs/contour. You may find something in there that provides a clue to the cause of the issue.
    • Make sure your connection is not being blocked by a firewall or proxy server.

Database connection issues
Jama may run but you encounter issues while trying to connect to your database during setup. There are a variety of issues that can cause a database configuration to fail but the most common is a Generic JDBC Exception. The Generic JDBC Exception is cryptic.

For this type of error, the best place to start is in the contour.log file. In the logs, the most common errors you will see are related to being unable to open a connection to the database. This usually means there is something wrong with the configuration. In addition, take a look at the following:

  • If you are using Oracle, verify that the Oracle jdbc driver is located in the correct directory. 
  • Verify that the URL to the database and/or the credentials used to access the database are correct. To do so, log into the database directly using the credentials you are trying to use for Jama. Perform this test from a separate workstation and the Jama server itself. 
  • Verify that the Jama server can communicate with the database server using tools like ping or telnet. If you cannot connect to the database server from your Jama server using those tools, contact your system administrator for assistance. 

Oh no! page
If you see the Oh no! page while trying to configure the database, take a look in the technical details window. It may provide some useful clues.

The above error indicates that the user trying to access the database doesn't have edit permissions. Verify that the user connecting to the database has the correct level of permissions to the database as discussed in the user guide.
NOTE: In Jama 2014.1, we used the Microsoft JDBC driver and, after research, determined the jTDS JDBC driver is faster. In versions of Jama 2014.2 and newer, Jama uses the jTDS JDBC driver which is bundled with the Jama download. Your existing file, located in contour_home, may still be populating a URL to use the old driver. There is an article on the community with instructions on how to fix this.
Updates fail
There are times where the patch installation on the Data Updates page will fail. This occurs most often when upgrading from versions prior to Jama 2014.2 and using Oracle as your database. It has been known to happen with MSSQL as well, but with less frequency.

  • Depending on the version of Jama you are upgrading from, you may need to perform a step upgrade
  • If the failure occurs while installing the patches, you should contact support for assistance. We will want to see the contour.log while troubleshooting.
  • If you receive an error while updating the database but the installation continues and completes, the upgrade probably worked but you should submit a Support ticket and have us take a look at your contour.log file to be sure your system is healthy.

Indexing fails
The indexing process may fail with an error message. If that happens, take a screenshot or somehow record the error message for support. How to proceed depends on what happens next:

  • If indexing fails but you can continue with setup and it appears to complete successfully, you should attempt to run a full re-index of Jama using the instructions from this article on the community
  • If indexing fails and the installation process does not complete, submit a Support ticket. We are going to want to look at the contour.log for additional information on why the problem occurred. 

Issues after the Upgrade

You see items in Jama that should not be there.
These could be things like items you deleted in Jama prior to the upgrade and now seem to have returned. You most likely did not delete the old search indexes before upgrading. To fix the issue perform a re-index.
You do not see items in Jama that should be there. 
This is usually an indication of a bad index. Perhaps the indexing process during installation did not complete even though it appeared to have. Again, you should try running a full re-index to see if it addresses the issue.
Jama is not performing as expected.
If you are experiencing performance issues after an upgrade, we will need to proceed with troubleshooting a performance issue as detailed in this community article. At this point please contact support for assistance.