Skip to main content

500 Server Error

Symptoms​

When navigating to a Mango page in the browser, the page fails to load and Mango displays a "500 - Server Error" or "Internal Server Error" message. This may affect all pages or only specific pages. In some cases, the Mango API endpoints also return 500 errors, while in other cases only the web UI is affected.

Common Causes​

  1. Corrupted work directory -- Mango uses a work directory to hold pre-compiled web pages and cached resources for better performance. This directory can become corrupted if the computer is power-cycled or the Mango process is killed without a clean shutdown. When the cached files are invalid, the web server cannot serve pages correctly and returns a 500 error.

  2. Database connection lost -- If the database server (MySQL, MariaDB, or H2) becomes unavailable or the connection pool is exhausted, Mango cannot retrieve the data needed to render pages. This results in 500 errors on pages that require database queries.

  3. Module crash or incompatibility -- A faulty or incompatible module can throw uncaught exceptions during page rendering, causing a 500 error. This is especially common after upgrading Mango core without updating all installed modules to compatible versions.

  4. Out of memory (OOM) -- When the JVM runs out of heap space, Mango cannot allocate memory to process requests. This produces 500 errors across all endpoints and may also generate java.lang.OutOfMemoryError entries in the log.

  5. Corrupted mangoUI-settings -- If the UI settings JSON stored in the database contains invalid data (such as malformed theme colors or missing required fields), the UI bootstrap process fails and produces 500-like errors or blank pages with JavaScript exceptions.

  6. Disk full -- If the filesystem where Mango stores its database, logs, or work directory runs out of space, write operations fail and Mango cannot function correctly.

Diagnosis​

Step 1: Check the Log File​

Open <MA_HOME>/logs/ma.log and look for ERROR entries near the time the 500 error occurred. The log will typically contain a Java stack trace that identifies the root cause.

Look for these patterns:

  • java.lang.OutOfMemoryError -- The JVM is out of heap space.
  • java.sql.SQLException or Connection refused -- Database connectivity issue.
  • FileNotFoundException or IOException in the work directory path -- Corrupted work directory.
  • NullPointerException or ClassNotFoundException in a module package -- Module error.
  • No space left on device -- Disk is full.

Step 2: Check System Resources​

Verify the host system has adequate resources:

# Check disk space
df -h

# Check memory usage
free -m

# Check if the Mango process is running and its memory usage
ps aux | grep mango

Step 3: Check the Browser Console​

Open the browser developer tools (F12 or Ctrl+Shift+J) and check the Console tab for JavaScript errors. If the error is related to the UI bootstrap (such as $injector:modulerr or theme-related errors), the mangoUI-settings JSON in the database may be corrupted.

Step 4: Test the REST API​

Try accessing a simple API endpoint directly to determine if the issue is UI-specific or system-wide:

GET /rest/latest/server/system-info

If the API responds normally but the UI returns 500 errors, the issue is likely in the work directory or UI settings. If the API also fails, the issue is at a deeper level (database, memory, or module).

Solutions​

Solution for Corrupted Work Directory​

This is the most common cause and the simplest to fix:

  1. Stop Mango.
  2. Delete the work directory located at <MA_HOME>/work/.
  3. Start Mango. The work directory will be automatically rebuilt.

Mango will take slightly longer to load pages on the first access after clearing the work directory, as it needs to recompile and cache the web resources.

Solution for Database Connection Issues​

  1. Verify the database server is running and accessible.
  2. Check the database connection settings in <MA_HOME>/env.properties.
  3. For H2 databases, ensure no other process has locked the database file.
  4. For MySQL/MariaDB, test the connection independently: 
    mysql -h localhost -u mango_user -p mango_database
  5. If the connection pool is exhausted, increase the pool size in env.properties: 
    db.pool.maxActive=100
  6. Restart Mango after making configuration changes.

Solution for Module Crashes​

  1. Stop Mango.
  2. Check ma.log for the specific module causing the error (the stack trace will reference the module's Java package).
  3. Remove the problematic module's .jar file from <MA_HOME>/web/modules/.
  4. Start Mango and verify the error is resolved.
  5. Download the correct version of the module from the Mango store and reinstall it.

Solution for Out of Memory​

  1. Increase the JVM heap size in the Mango configuration: 
    # In env.properties or wrapper configuration
    wrapper.java.maxmemory=2048
  2. Review the number of enabled data points and data sources. A very large number of active points consumes significant memory.
  3. Check purge settings -- retaining too much historical data in the point value cache can exhaust memory.
  4. Consider upgrading the server hardware or moving to a machine with more RAM.

Solution for Corrupted UI Settings​

If the browser console shows AngularJS bootstrap errors related to themes or settings:

  1. Access the SQL console. If the main UI is broken, navigate to /login.htm to access the legacy UI (Mango 3.x), or use an external database client.
  2. Delete the corrupted UI settings: 
    DELETE FROM jsonData WHERE xid = 'mangoUI-settings'
  3. Restart Mango. Default UI settings will be regenerated.

Solution for Disk Full​

  1. Free disk space by deleting old log files, temporary files, or old backups.
  2. Run a manual purge of point values if the database has grown too large.
  3. Move the database or log directory to a larger disk if the current filesystem is too small.
  4. Restart Mango after freeing adequate space.

Prevention​

  • Always shut down Mango cleanly using the proper shutdown command or service stop. Never kill the process or power-cycle the machine while Mango is running.
  • Monitor disk space on the Mango server. Set up alerts for low disk space conditions.
  • Configure JVM heap size appropriately for your workload. A minimum of 1 GB is recommended for most installations, with 2-4 GB for large deployments.
  • Keep all modules updated to versions compatible with your Mango core version.
  • Set up regular database backups so you can recover quickly from corruption.
  • Monitor the ma.log file for warning messages that may indicate developing problems before they cause outages.