Skip to main content

Troubleshooting

This section covers common problems and solutions encountered when deploying, configuring, and operating Mango. Each guide follows a structured approach: identify the symptoms, determine the cause, and apply the appropriate fix.

How to Use This Section​

When you encounter an issue with Mango, start by identifying the category that best matches your problem. Each troubleshooting page provides a structured walkthrough from symptoms through diagnosis to resolution. If your issue spans multiple categories, check the most relevant section first and follow any cross-references.

Before diving into specific troubleshooting pages, always check the ma.log file located at <MA_HOME>/logs/ma.log. This log captures startup messages, runtime errors, and warnings that often point directly to the root cause of a problem.

Categories​

  • Installation Issues -- Problems with Mango startup, upgrades, and initial configuration. Covers situations where Mango fails to start, hangs during initialization, or encounters errors after an upgrade.

  • Performance -- Memory exhaustion, high CPU usage, and work item queue backlogs. Use this section when Mango is running but responding slowly, consuming excessive resources, or generating out-of-memory errors.

  • Database -- Database conversion failures, corruption recovery, and server errors. Covers HTTP 500 errors, H2 and MySQL/MariaDB issues, and data migration problems.

  • Data Source Issues -- Protocol-specific troubleshooting for Modbus, BACnet, OPC UA, and other data source types. Includes problems with disappearing data points, communication failures, and configuration requirements.

  • UI Issues -- Dashboard rendering problems, blank dropdowns, chart display errors, and browser compatibility issues. Covers both the standard Mango UI and custom dashboard pages.

General Resources​

  • Licensing FAQ -- Answers to common questions about Mango license activation, offline installation, license transfers, and troubleshooting license errors.

  • Reporting Bugs -- How to report bugs effectively, what information to include, and where to submit issues for the fastest resolution.

General Troubleshooting Steps​

When encountering any issue with Mango, the following general steps apply:

  1. Check the logs. Open <MA_HOME>/logs/ma.log and look for ERROR or WARN entries near the time the problem occurred.
  2. Check system resources. Verify that the host machine has sufficient memory, disk space, and CPU capacity. Use the System Information page in Mango or OS-level tools.
  3. Review recent changes. Did you recently upgrade Mango, install a new module, change a configuration file, or modify data source settings? Rolling back the most recent change often resolves the issue.
  4. Clear the work directory. If Mango is producing unexpected UI behavior, stopping Mango and deleting the <MA_HOME>/work directory forces a rebuild of cached and compiled resources on the next startup.
  5. Restart Mango cleanly. Always shut down Mango using the proper shutdown command or service stop rather than killing the process or power-cycling the machine. Unclean shutdowns can cause database corruption.
  6. Search the forum. The Mango community forum contains years of user-reported issues and solutions that may match your situation.