Troubleshooting Steps

If you run into a problem using Mifos, try the following:

1. Review the FAQs. Scroll down to see workarounds and tips for some common problems in Mifos.
2. Look at the log(s). Mifos application errors are written to a mifos_log.log file in your Tomcat bin directory (for example, C:
   Program Files
   apache-tomcat-6.0.18
   bin). Mifos also logs changes in status for accounts and clients, among many other things. To see the logs, click the View change log and View status history links in the Mifos user interface.
3. Search for workarounds. See the Mifos bug database and the Known Issues list for the Mifos version you're running to see if the problem you're experiencing is known and has a workaround.
4. Browse the listservs. Access the Mifos users and functional listservs to see if the Mifos community has already solved your problem.
5. See Mifos.org. The Mifos web site contains a broad array of information on how to use Mifos.
6. Reach out. If you can't find a solution to your problem, use the Mifos users listserv or the IRC channel to ask the Mifos community for help.

Frequently Asked Questions

Loans

I created a loan product but I don't see it in the "Loan instance name" list.

...

This is a known issue (issue 2123). The workaround is to change processes to cancel the loan and create a new one for the group.

Reporting

Mifos BIRT default reports are not working?

BIRT reports in Mifos uses default database configurations. BIRT reports are not able to use custom database configurations (local.properties).

...

You can enable detail BIRT logging. Change the tomcat/webapp/mifos/WEB-INF/web.xml and change the logging level from OFF to WARNING

    <context-param>
        <param-name>BIRT_VIEWER_LOG_LEVEL</param-name>
        <param-value>OFF</param-value>
    </context-param>

You can use the stack trace from the logs to get more details and it's useful for asking question on mailing list.

After restarting Mifos I receive a permission error when viewing a report that previously worked.

This is a known issue (issue 2255) that happens with certain data sets. The workaround is to reload every report after restarting Mifos.

...

1. Remove the mustMatch property from any parameters. This will get rid of spurious radio buttons for each parameter.
2. Change the default value of any parameters from 3 to -2 (possibly cascaded parameters only?). This will initialize parameter pulldowns with the proper "-Select--" text.
3. Remove any PageBreakBefore or PageBreakAfter properties.

Installing

The .war works on another machine but not mine.

Check the password on your database. For Mifos version 1.2 or older, you may need to unpack the .war file, update build.properties and hibernate.properties with the correct MySQL username and password. For Mifos versions after 1.2, check your LocalPropertiesFile. Also, what version of Java have you installed? If a later version of Java was used to build the.war file, a machine running an earlier version may not be able to use it.

Removing or Upgrading

How do I remove Mifos from my machine?

1. Log out of Mifos.
2. Stop the Tomcat instance that's running Mifos by either executing the shutdown script in your Tomcat bin directory or, if you're running Tomcat as a Windows service, by stopping it.
3. Delete the following:

• The mifos folder under Tomcat/webapps. Any custom reports you created are in Tomcat/webapps/mifos/report.
• The mifos folder under Tomcat/work/Catalina/localhost.
• The mifos.war file in your Tomcat webapps folder.

I'm using an earlier version of Mifos - how do I install a completely new version?

If you're running an earlier version of Mifos that you don't want to keep, use the following procedure to install a completely new version:

1. Remove Mifos as described above.
2. Drop the mifos schema in MySQL Query Browser.
3. Download the new Mifos installation package and extract the Mifos .war file.
4. Follow the instructions in the `Mifos INSTALL file <https://mifos.dev.java.net/source/browse/_checkout_/mifos/tags/v1.4/mifos/INSTALL?rev=HEAD&view=markup>`_ to install and run the newer version of Mifos.

How do I upgrade to a new version of Mifos while preserving my existing data?

1. Remove Mifos as described above. If you created custom reports, make a copy of the report folder under Tomcat/webapps/mifos before you delete the webapps/mifos folder.
2. Download the new Mifos installation package and extract the Mifos .war file.
3. Follow the instructions in the `Mifos INSTALL file <https://mifos.dev.java.net/source/browse/_checkout_/mifos/tags/v1.4/mifos/INSTALL?rev=HEAD&view=markup>`_ to install and run the newer version of Mifos.

Performance

I'm receiving a Java Heap Memory error when I try to run Mifos.

As described in the `Mifos INSTALL file <https://mifos.dev.java.net/source/browse/_checkout_/mifos/tags/v1.1.4/mifos/INSTALL?rev=HEAD&view=markup>`_ , set your CATALINA_OPTS environment variable as follows:

CATALINA_OPTS ... -Xms1024M -Xmx1024M -XX:MaxPermSize=256m

Database

I'm receiving an "Unable to connect to database" error...

This error message appears when one or more of the following occurs:

...

• For information on how to start MySQL, see the topic Start/Stop Service in the MySQL Administrator online help.
• For information on how to customize your database connection - for example, by using a non-default user name and password or a port other than 3306 - see Customizing your Database Connection.

I'm receiving a "Database version is too old to be upgraded" error...

This error message appears when:

...

See DatabaseVersionPersistence.java in the Mifos source code for more information about what causes this error.

How do I backup my Mifos database?

To backup your Mifos database using the MySQL Administrator user interface:

...

mysqladmin -u root flush-logs

How do I restore my Mifos database?

To restore your Mifos database using the MySQL Query Browser and MySQL Administrator user interface:

...

mysql -u root -p db_name < source_sql_file.sql

How do I run the Mifos database and the Mifos application on different machines?

Follow the instructions in the `Mifos INSTALL file <https://mifos.dev.java.net/source/browse/_checkout_/mifos/tags/v1.1.4/mifos/INSTALL?rev=HEAD&view=markup>`_ with the following exceptions:

...

If using Mifos greater than version 1.2, see LocalPropertiesFile for database connection customization instructions.

I'm experiencing database upgrade problems...

See Database Standards.

Building Mifos

Tomcat is running, but Mifos won't load.

Check your LocalPropertiesFile (or build.properties and hibernate.properties if you're running Mifos version 1.2 or older) to make certain that your username/password match your install.

I can't run individual tests.

Not all tests clean up properly after completing. Try running mvn clean install to make sure the test database is in a good state.

I can't run individual tests in Eclipse

Try cleaning up Eclipse quot run configurations quot

I can't fetch any page in Mifos due to a NoClassDefFoundError

If JSP pages were moved in the source tree, it may be necessary to manually remove the directory where Tomcat stores precompiled JSP pages. This is generally CATALINA_HOME/work . When running Mifos under the Eclipse WTP, this directory will be something like HOME/workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp1/work .

Mock struts tests fail, cannot find /WEB-INF/web.xml

Execute mvn process-resources.

Running Mifos Acceptance Tests

Tomcat is running, but can't start Mifos or login.

Make certain that acceptance_test database settings in your LocalPropertiesFile file match your mysql install.

Firefox crashes when running tests.

Skype installs a Firefox extension that can cause Selenium RC to crash. Workaround is to remove the Skype extension from your Firefox or Chrome instance.