Skip to main content

Startup Stuck at 40% After Upgrade

Symptoms​

After upgrading Mango to a newer version, the startup progress bar freezes at or near 40%. The Mango web interface does not become available. The process appears to be running, but no further progress is made. In some cases, the progress may advance very slowly, taking significantly longer than a normal startup.

Common Causes​

  1. Database and module version mismatch -- The database was copied from an older version of Mango into a freshly installed new version, without allowing the upgrade process to run the required database migrations alongside the module installations.
  2. NoSQL database corruption -- The high-performance NoSQL database (used for point value storage) has become corrupted, typically due to an unclean shutdown such as a power failure or forcefully killing the Mango process.
  3. Corrupt or incompatible module -- A module .jar file in the <MA_HOME>/web/modules/ directory is damaged, incompatible with the new Mango core version, or was only partially downloaded.
  4. Java version incompatibility -- The installed Java runtime does not meet the minimum version requirement for the new Mango version. Mango 4.x requires Java 11+, and Mango 5.x requires Java 17+.
  5. Insufficient system resources -- The upgrade process (especially database migrations) can require more memory or disk space than normal operations. Running out of heap space during migration causes the process to stall.

Diagnosis​

Step 1: Check the Log File​

Open <MA_HOME>/logs/ma.log and look for the most recent entries. The log will indicate where in the startup process Mango stopped progressing.

  • If you see messages about database schema upgrades or table conversions, the system is likely performing a migration. This can take a long time on large databases. Let it continue unless errors appear.
  • If you see NoSQL repair or corruption detected messages, the NoSQL database is being scanned and repaired. This can take from minutes to hours depending on database size.
  • If you see ClassNotFoundException or NoSuchMethodError entries, a module is incompatible with the current Mango core version.
  • If you see OutOfMemoryError, the JVM needs more heap space to complete the upgrade.

Step 2: Verify the Upgrade Was Performed Correctly​

The correct upgrade procedure is:

  1. Unzip the latest Mango distribution files but do not start Mango yet. This leaves all modules in their zipped state ready for installation.
  2. Copy your existing database from the older Mango installation into the new Mango file system (for example, into <MA_HOME>/databases/).
  3. Start Mango. The modules will be installed and a full database upgrade will be performed together, ensuring consistency.

A common mistake is:

  1. Installing a clean version of the latest Mango (which creates a new, empty database).
  2. Shutting down Mango and then copying in a database from an older version.
  3. Starting Mango -- this fails because the module installation and database migration were not coordinated.

Step 3: Check for NoSQL Corruption​

If the log shows messages related to NoSQL repair or scanning, the system is attempting to recover from corruption. This repair process runs automatically and can take a significant amount of time for large databases. Monitor the log for progress messages. If the repair completes successfully, Mango will continue its normal startup sequence.

Solutions​

Solution for Database/Module Mismatch​

If the upgrade was performed incorrectly (database was copied after initial startup):

  1. Stop Mango.
  2. Delete the current database and the work directory.
  3. Copy the old database into the new Mango installation directory.
  4. Ensure all module .zip files are present in the <MA_HOME>/web/modules/ directory.
  5. Start Mango and allow the full upgrade to run.

Solution for NoSQL Corruption​

If the NoSQL database is corrupted:

  1. Allow the automatic repair process to complete. Monitor ma.log for progress.
  2. If the repair process does not complete or produces errors, stop Mango and delete the NoSQL database files (typically located in <MA_HOME>/databases/). Mango will create a new NoSQL database on startup, but historical point values stored only in NoSQL will be lost.
  3. If you have a backup, restore the NoSQL database files from the backup before starting Mango.

Solution for Incompatible Modules​

  1. Stop Mango.
  2. Move all module .jar files out of <MA_HOME>/web/modules/ to a temporary location.
  3. Start Mango with only the core modules. If it starts successfully, the issue is an incompatible module.
  4. Add modules back one at a time, restarting after each, to identify the problematic module.
  5. Download the correct version of the module that matches your Mango core version from the Mango store.

Solution for Insufficient Memory​

Increase the JVM heap size by editing the <MA_HOME>/env.properties file or the Mango service configuration:

# Example: increase max heap to 2 GB
wrapper.java.maxmemory=2048

Restart Mango after making this change.

Prevention​

  • Always follow the correct upgrade procedure: unzip first, copy the database second, then start Mango.
  • Always shut down Mango cleanly before powering off the machine. Use the proper shutdown command or stop the service gracefully.
  • Maintain regular backups of both the SQL database and the NoSQL point value database.
  • Before upgrading, verify that all installed modules have compatible versions available for the target Mango version.
  • Ensure the system has adequate memory and disk space before beginning an upgrade, especially for large databases.
  • Restart Issues — Diagnose problems with Mango restarting or shutting down unexpectedly
  • Server Error 500 — Troubleshoot server errors that may prevent proper startup
  • Database Corruption — Detect and repair database issues that block startup
  • Reporting Bugs — How to report startup issues with proper diagnostic information