Troubleshooting Installation

MySQL Database Engine

Be sure the MySQL database engine is running first.

If MySQL is not running, the following messages may appear on OpenMRS console log as well as in the Tomcat log file:

Error creating bean with name 'messageSourceServiceTarget' defined in class path resource applicationContext-service.xml: :
followed by stack trace

These errors may be related to MySQL Database startup.

MySQL Version

There are multiple different versions of MySQL provided with the link given in the developer’s guide. It could be confusing for new developers.

The easiest way is to download using apt.

Be sure to download MySQL server instead of MySQL client.

Installing MySQL 5.6 in newer releases of Ubuntu (like 20.04)

One might face difficulties in setting up MySQL 5.6 in the newer releases of Ubuntu (like 18.04 or 20.04). Nothing to worry. Here is a step-by-step guide for doing that.

  • Download the MySQL Community Server DEB Bundle from here.

    • Select 5.6.* as Product Version, Debian Linux as Operating System and then download the 32-bit or 64-bit DEB Bundle as per the system's requirement.

    • It basically contains individual packages like mysql-common, mysql-community-client, mysql-client, mysql-community-server, etc.

  • Install the packages individually using dpkg -i <package-name>.deb

  • Note that it will be required to go in a certain order for installing the packages, which could be found out by trial-and-error (see the error messages if any for the other package's requirement).

  • In case there is some error for missing dependencies, run sudo apt-get install -f

An example case:

I use Ubuntu 20.04 and I went in the following order:

sudo dpkg -i mysql-common_5.6.47-1debian9_amd64.deb 
sudo dpkg -i mysql-community-client_5.6.47-1debian9_amd64.deb 
sudo dpkg -i mysql-client_5.6.47-1debian9_amd64.deb 
sudo dpkg -i mysql-community-server_5.6.47-1debian9_amd64.deb

After this, I got some errors (maybe because of the order I followed). I again did:

sudo dpkg -i mysql-common_5.6.47-1debian9_amd64.deb
sudo dpkg -i mysql-community-client_5.6.47-1debian9_amd64.deb

After this, I got some errors about missing dependencies, so I ran:

sudo apt-get install -f

That's it, MySQL 5.6 successfully got installed!

War file deploys in Tomcat but it won't start OpenMRS

Try this:

  • Go to MySQL command line (accessible from Start menu)
  • Type the following lines and press Enter after each one:

    use OpenMRS;
    create user openmrs identified by 'PASSWORD';
    GRANT ALL ON openmrs.* TO 'openmrs'@'%';
  • Go to C:\Documents and Settings\LocalService\Application Data\OpenMRS
  • There should be a file there called
  • In this file, ensure it says the following:

    ### Database connection properties
  • Copy the file into C:\Documents and Settings\YOURUSERNAME\Application Data\OpenMRS where YOURUSERNAME is the name you use to log in to windows. This is in case Tomcat looks there instead of in LocalService.

Where to find your

Windows XP

  • Under C:\Documents and Settings\YOURUSERNAME\Application Data\OpenMRS
  • Under C:\Windows\system32\config\systemprofile\Application Data\OpenMRS

Windows 7

  • Under C:\Users\YOURUSERNAME\AppData\Roaming\OpenMRS


  • Under /home/YOURUSERNAME/.OpenMRS
  • Under /usr/share/tomcatX/.OpenMRS

Troubleshooting Tomcat

For more troubleshooting tips see Troubleshooting Tomcat.


  1. Download the newest version of legacy UI.
  2. Find the legacy-version-SNAPSHOT.omod file
  3. Put it into the hidden folder ~/.OpenMRS/modules.
  4. Be sure to kill the previous operations running the webapp.
  5. Clear the browser cache.

  6. Rerun the webapp using command:
            mvn jetty:run

Running Maven

The time taken for maven to compile could vary for different computers.

Kill the previous mvn clean install or mvn jetty: run every time you rerun maven. Otherwise, it might gives a following error indicating address already in use.


HTTP 500 error

After opening http://localhost:8080/openmrs in the web browser, you might encounter the following error.

Close the window and kill the prior operations. 

 Rerun mvn jetty:run in the webapp folder and it usually works.