Skip to main content

Installation Issues

This section covers problems that occur during Mango installation, upgrades, and startup. These issues typically manifest as Mango failing to start, hanging during initialization, or encountering errors immediately after an upgrade.

Common Installation Issues​

  • Startup Stuck at 40% After Upgrade -- Mango hangs during startup after upgrading, typically around the 40% progress mark. Caused by database/module version mismatches or NoSQL database corruption from unclean shutdowns.

  • Mango Won't Restart -- Troubleshoot Mango restart failures including restart flag file issues, systemd configuration problems, port conflicts, and corrupted PID files.

General Installation Troubleshooting​

Check Java Version​

Mango requires a compatible Java runtime. If the wrong version is installed, Mango may fail to start with cryptic errors. Verify your Java version by running:

java -version

Mango 4.x requires Java 11 or later. Mango 5.x requires Java 17 or later. Using an incompatible version is one of the most common causes of startup failures.

Verify File Permissions​

On Linux systems, ensure the Mango installation directory and all subdirectories are owned by the user running the Mango service. Incorrect file permissions prevent Mango from reading configuration files, writing logs, or accessing the database.

chown -R mango:mango /opt/mango

Check Port Availability​

Mango defaults to port 8443 for HTTPS. If another application is already using this port, Mango will fail to bind and may not start. Check for port conflicts:

# Linux
ss -tlnp | grep 8443

# macOS
lsof -i :8443

To change the port, edit the env.properties file in <MA_HOME> and set the web.port or ssl.port property.

Review the Startup Log​

The most important diagnostic tool is the ma.log file located at <MA_HOME>/logs/ma.log. This file records the entire startup sequence and will contain error messages explaining why Mango failed to start. Look for lines containing ERROR or Exception near the end of the file.