Skip to main content

Mango Won't Restart

This page covers common causes and solutions when Mango fails to restart after a shutdown, UI-initiated restart, or system reboot.

Symptoms​

  • Clicking "Restart" in the Mango UI does not bring the system back online.
  • After a system reboot, Mango does not start automatically.
  • The Mango process terminates but a new process never starts.
  • The startup log shows errors related to port binding, lock files, or the JVM failing to launch.
  • The systemd service reports "failed" or "inactive" status after a restart attempt.

Common Causes​

  1. Restart flag file not created or not detected: Mango uses a shutdown flag mechanism to signal that a restart is requested rather than a clean stop. If the flag is not written correctly, the wrapper process exits without restarting.
  2. Systemd or init system not configured for automatic restart: If Mango is running as a systemd service but the unit file does not include Restart=on-failure or Restart=always, the service manager will not restart Mango after it stops.
  3. Port conflict after restart: Another process (or a lingering Mango instance) has bound to the configured HTTP/HTTPS port before the new instance can start.
  4. Corrupted PID file: A stale PID file from the previous process prevents the new instance from starting because the wrapper believes Mango is already running.
  5. Java process not found: The JAVA_HOME environment variable is not set correctly in the service configuration, or the Java binary is not on the system PATH available to the service user.
  6. Insufficient file descriptors or memory: The operating system refuses to launch a new JVM due to resource limits (ulimits) that are too low for the Mango process.
  7. Database lock not released: The embedded H2 database may not have released its file lock cleanly, preventing the new instance from acquiring it.

Diagnosis​

Check if Mango is still running​

# Check for any running Mango/Java processes
ps aux | grep -i mango
ps aux | grep java

# Check the configured port (default 8080)
ss -tlnp | grep 8080
# or on older systems:
netstat -tlnp | grep 8080

If a Mango or Java process is still running, the previous instance did not shut down cleanly.

Check the systemd service status​

sudo systemctl status mango.service

Look for:

  • Active: failed -- The service tried to start and failed.
  • Active: inactive (dead) -- The service stopped and was not restarted.
  • Error messages in the journal output.

For more detail:

sudo journalctl -u mango.service --since "10 minutes ago" --no-pager

Check the Mango log file​

Review <MA_HOME>/logs/ma.log for errors during the most recent startup attempt. Common error patterns:

  • java.net.BindException: Address already in use -- Port conflict.
  • org.h2.jdbc.JdbcSQLException: Database may be already in use -- H2 lock not released.
  • java.lang.OutOfMemoryError -- Insufficient heap space during initialization.

Check the PID file​

# Typical location
cat <MA_HOME>/bin/ma.pid

# Check if a process with that PID actually exists
kill -0 $(cat <MA_HOME>/bin/ma.pid) 2>/dev/null && echo "Process exists" || echo "No such process"

Solutions​

Solution 1: Kill the lingering process and restart​

If the previous Mango process is still running:

# Graceful stop attempt
sudo systemctl stop mango.service

# If that doesn't work, find and kill the process
ps aux | grep java | grep mango
kill <PID>

# Wait a few seconds, then force kill if necessary
kill -9 <PID>

# Remove stale PID file if present
rm -f <MA_HOME>/bin/ma.pid

# Start fresh
sudo systemctl start mango.service

Solution 2: Fix the systemd unit file​

Ensure the Mango service unit file includes restart directives. Edit the service file (typically /etc/systemd/system/mango.service):

[Service]
Type=simple
ExecStart=/opt/mango/bin/start-mango.sh
Restart=on-failure
RestartSec=10

After editing:

sudo systemctl daemon-reload
sudo systemctl restart mango.service

Solution 3: Resolve port conflicts​

If another application is using the port:

# Find what is using port 8080
ss -tlnp | grep 8080

Either stop the conflicting application or change Mango's port in mango.properties:

web.port=8443

Solution 4: Release the H2 database lock​

If the H2 database lock was not released cleanly:

# Remove the H2 lock file (only when Mango is NOT running)
rm -f <MA_HOME>/databases/*.lock.db

Then restart Mango. If the issue persists, check for database corruption (see Database Corruption Recovery).

Solution 5: Verify Java installation and environment​

# Check that Java is available to the service user
sudo -u mango java -version

# Verify JAVA_HOME in the startup script or service file
grep -i java_home <MA_HOME>/bin/start-mango.sh

If Java is not found, install it or correct the JAVA_HOME path in the startup script or systemd environment configuration.

Solution 6: Increase system resource limits​

Edit the systemd unit file to raise limits:

[Service]
LimitNOFILE=65536
LimitNPROC=65536

Or set system-wide limits in /etc/security/limits.conf:

mango soft nofile 65536
mango hard nofile 65536

Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart mango.service

Solution 7: Restart manually for diagnosis​

If the service-based restart fails, try starting Mango manually to see the full console output:

cd <MA_HOME>
./bin/start-mango.sh

This shows startup errors directly in the terminal, making it easier to identify the root cause.

Prevention​

  • Configure systemd with Restart=on-failure to ensure automatic restart after unexpected termination.
  • Monitor the Mango process with a health check script or external monitoring tool that alerts if the HTTP port becomes unreachable.
  • Use the graceful shutdown endpoint rather than killing the process directly. Allow Mango time to flush data and release locks.
  • Set appropriate JVM heap sizes (-Xms and -Xmx) in the startup script to prevent out-of-memory crashes during startup.
  • Regularly back up the H2 database if using the embedded database, so that a corrupted lock file does not become a data-loss event.
  • Keep the startup script and systemd unit file under version control so that changes can be tracked and reverted if needed.
  • Startup Stuck — Troubleshoot Mango failing to start or hanging during initialization
  • Out of Memory — Memory exhaustion that can cause unexpected restarts
  • High CPU Usage — CPU issues that may trigger watchdog restarts
  • Reporting Bugs — How to report restart issues with proper diagnostic information