Skip to main content

Starting in Safe Mode

Safe Mode allows you to start Mango with all data sources disabled. This is essential for troubleshooting situations where a misconfigured data source prevents Mango from starting properly, causes excessive resource consumption, or triggers a cascade of errors that makes the system unusable.

When to Use Safe Mode​

Common scenarios where safe mode is needed:

  • A data source is causing Mango to crash or hang during startup.
  • A scripting data source contains an infinite loop or resource-intensive operation.
  • A data source is generating thousands of events per second, overwhelming the system.
  • You need to access the Mango UI to modify or delete a problematic data source, but normal startup fails.

How to Activate Safe Mode​

You activate safe mode by creating an empty file named SAFE (with no file extension) in the data/core/ directory under your Mango data path.

Finding the Data Path​

The data path is defined by the paths.data property in your mango.properties file. If paths.data is not set, it defaults to the Mango installation directory (MA_HOME). The SAFE file should be placed at:

${paths.data}/data/core/SAFE

For a default installation, this is typically:

MA_HOME/data/core/SAFE

Linux / macOS​

cd MA_HOME/data/core/
touch SAFE

Replace MA_HOME with the actual path to your Mango installation (e.g., /opt/mango).

Windows​

  1. Open the Notepad application.
  2. Navigate to File > Save As...
  3. In the file name field, type "SAFE" (with the quotation marks). The quotes are important -- without them, Windows will append a .txt extension.
  4. Save the file to the MA_HOME\data\core\ directory.

What Happens in Safe Mode​

When the SAFE file is present during startup:

  1. Mango starts normally and loads all configuration from the database.
  2. All data sources are set to disabled in the database.
  3. No data sources will poll, no connections will be opened, and no data will be collected.
  4. The Mango UI is fully accessible, allowing you to examine and modify data source configurations.

Recovering from Safe Mode​

After starting in safe mode:

  1. Log in to the Mango UI.
  2. Navigate to the data source that was causing problems and fix or delete it.
  3. Manually re-enable the data sources you want to run. Safe mode disables all data sources in the database, so you must re-enable each one.
  4. Delete the SAFE file from the data/core/ directory.
  5. Restart Mango.
warning

Safe mode disables data sources directly in the database. If you have many data sources, remembering which ones were enabled before safe mode can be difficult. As a precaution, export a JSON backup of your data source configuration before activating safe mode (if possible), or keep a record of your enabled data sources. You can also use a previous data source JSON export to re-enable them by importing it after recovery.

Automating Safe Mode in Scripts​

For automated recovery workflows, you can script safe mode activation:

#!/bin/bash
# Activate safe mode and restart Mango
touch /opt/mango/data/core/SAFE
systemctl restart mango

After making repairs through the REST API or UI, remove the file and restart:

rm /opt/mango/data/core/SAFE
systemctl restart mango