Common Troubleshooting - Mifos 2.x Archieve

Owned by Former user (Deleted)
Last updated: May 18, 2015 by Dayna Harp (Unlicensed)
8 min read

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.

A common issue that some users run into is not seeing a certain loan product in the Loan instance name list when they open a loan account for a user or group.

In Mifos, when you create a loan product, you have to assign it a repayment frequency – either every X number of weeks or every X number of months. You also specify whether a loan product is for clients or groups.

When you open a loan account for a client or group, Mifos filters the list of available products based on for whom you're opening the account - either a client or group. Mifos also filters the list based on repayment frequency. Loan products that do not have a repayment frequency that matches the client meeting frequency do not show up in the list. For example, if you created a loan product with monthly repayments, then loan products for clients with weekly repayments will not show up in the Loan instance name list box. However, if you created a loan product that has repayments once every 4 weeks, then because this loan product's repayments are based on weeks, this product will appear for clients who have weekly meetings.

How do I disburse a loan on a date other than the meeting date?

Use a setting called Loan Set Independent of Meeting. See Database-Configured Settings for more information.

How do I change the name of a loan officer?

Loan officers are stored as System Users in Mifos. To change a loan officer's name:

  1. On the Admin tab, click View system users.
  2. Search for the loan officer whose name you want to change.
  3. Select the loan officer's name then click Edit user information.
  4. Change the name.
  5. Click Preview > Submit.

I get an invalid disbursement date error when I edit a group loan, even though the date is valid.

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 would have to use BIRT designer to edit the database parameters in reports. Use BIRT designer 2.5.1 only to avoid report compatibility issues.

http://archive.eclipse.org/birt/downloads/build.php?build=R-R1-2_5_1-200909220630 (Download ALL in one BIRT designer 2.5.1)

Open tomcat/webapp/mifos/report/BirtReportResource/MifosReport.rptlibrary in BIRT designer, go to Outline -> Data Sources -> double click on MifosReport.rptlibrary (Change the database parameters as per your need)

To know more details check the issues

MIFOS-2431        (Add in ability for BIRT to use db connection parameters from within Mifos)

MIFOS-2840        (BIRT MifosJDBCDataSource(MifosReport.rptlibrary) should pick database parameters from database configuration file of Mifos)

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.

I was running Mifos 1.3.x (or earlier) and just upgraded and now my BIRT reports don't work.

BIRT was upgraded from 2.1.2 to 2.5.1 with Mifos v1.4. For the most part, reports written for Birt 2.1.2 or Birt 2.3.2.2 should still work under Birt 2.5.1. However, Birt compatibility is not perfect. If you have trouble with reports not running or displaying strangely, here are some things to try.

First, download Birt 2.5.1 (http://download.eclipse.org/birt/downloads/), load your report in the editor, then save it. This load/save step will do all the recommended upgrades from your older version. Then, edit the resulting file to change a few things the upgrader doesn't seem to handle quite right:

  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:

  • MySQL is not running.
  • MySQL is listening on a different port than Mifos is expecting (by default, 3306).
  • You are using an incorrect username or password for MySQL. Mifos assumes that your MySQL username is root and your password is mysql.

To check whether MySQL is running and listening on a certain port, enter telnet <hostname> <port> at a command prompt. For example:

telnet localhost 3306

If MySQL is running on the machine you specify and listening on the port number you entered, you will get a response that includes the server's MySQL version number. For example:

5.0.67-community-nt

  • 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:

  • you are using the wrong database
  • your database has been corrupted
  • the database version is too old and Mifos can't figure out how to upgrade it

Make sure the correct databases are specified in your LocalPropertiesFile.

If your database has become corrupt, follow the installation documentation to manually re-create your database.

If your database version is too old, you may be able to download an older version of Mifos, upgrade using that, then use the more recent version of Mifos to upgrade again.

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:

  1. In MySQL Administrator, click Backup in the left pane.
  2. Click New Project.
  3. Enter a name in the Project Name text box. For example, mifos_012009
  4. In the Schemata list, highlight the Mifos schema.
  5. Click the > arrow to put the data into the Backup Content area.
  6. Click Execute Backup Now.
  7. In the Save As dialog box, select where you want to save the backup.

To backup your Mifos database from the command line:

mysqldump ---add-drop-table -u root -p db_name > target_sql_file.sql

For incremental backups, you can turn on the binary log, then do something like this monthly:

``mysqldump u root --single-transaction --create-options --flush-logs --flush-privileges --master-data=2 --delete-master-logs --databases mifos mysql | gzip > /backups/full`date u +%Y%m-%dT%H:%M:%SZ`.sql.gz``

and something like this, every other day:

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:

  1. If Mifos is running, log out.
  2. In MySQL Query Browser, drop the Mifos database by right-clicking mifos and selecting Drop Schema.
  3. In MySQL Administrator, click Restore in the left pane.
  4. Click Open Backup File and select the backup you created.
  5. Keep the default settings and click Start Restore. Start Mifos and verify that the restored data is there.

To restore your Mifos database from the command line:

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:

  • Install MySQL on the machine where the database will run.
  • Copy the sql folder from the Mifos .war to the machine where the database will run and execute the .sql scripts there.
  • On the machine where Mifos will run, modify the hibernate url in the deploymifosDB.properties file, changing localhost to the name of the machine running the database. For example:

hibernate.connection.url=jdbc:mysql://www.mydbhost.net:3306/mifos?useUnicode=true&characterEncoding=UTF-8

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.