How Music Assistant Safe Mode Works and When It Is Activated

Music Assistant safe mode starts only the core controllers and built-in providers while skipping all third-party providers, and it can be activated via command-line arguments, Home Assistant add-on options, or the MASS_SAFE_MODE environment variable.

Music Assistant is an open-source media server that aggregates music from various streaming sources and local libraries. When debugging provider-related crashes or ensuring system stability, administrators can start the server in safe mode to restrict the system to essential components only. This article explains exactly how safe mode functions in the music-assistant/server repository and the three methods available to activate it.

What Is Music Assistant Safe Mode?

Safe mode is a startup configuration that initializes only the core controllers and built-in providers while bypassing the asynchronous loading of regular (non-builtin) providers. This isolation is useful for troubleshooting when a specific third-party provider prevents the server from starting correctly, or when you need to guarantee that no external provider code runs during the session.

How to Activate Safe Mode

The safe mode flag is determined at startup by evaluating three possible sources in music_assistant/__main__.py. The server enters safe mode if any of these sources evaluate to true.

Command-Line Argument

Pass the --safe-mode flag when launching the server manually:

python -m music_assistant --safe-mode

Home Assistant Add-on Options

For Home Assistant installations, set the safe_mode option to true in the add-on's options.json file:

{
  "safe_mode": true,
  "log_level": "INFO"
}

Environment Variable

Export MASS_SAFE_MODE with any truthy value before starting the process:

export MASS_SAFE_MODE=1
python -m music_assistant

How Safe Mode Works Internally

The activation logic combines all three sources at lines 28-30 of music_assistant/__main__.py:

safe_mode = bool(
    args.safe_mode or hass_options.get("safe_mode") or os.environ.get("MASS_SAFE_MODE")
)

The resulting boolean is passed to the MusicAssistant constructor at line 34:

mass = MusicAssistant(data_dir, cache_dir, safe_mode)

Inside music_assistant/mass.py, the flag is stored on the instance as self.safe_mode. During the start() method, the system always loads built-in providers via self._load_builtin_providers(), but conditionally skips regular providers based on the flag at lines 240-246:

# load builtin providers (always needed, also in safe mode)

await self._load_builtin_providers()

# load regular providers (skip when in safe mode)

if not self.safe_mode:
    await self._load_providers()

This ensures that core services—including the web server, music controller, player controller, and cache—initialize normally, while third-party providers remain inactive.

Summary

• Safe mode restricts Music Assistant to core controllers and built-in providers, skipping all third-party provider loading
• Activation is possible via the --safe-mode CLI argument, the MASS_SAFE_MODE environment variable, or the Home Assistant add-on options.json configuration
• The flag evaluation occurs in music_assistant/__main__.py (lines 28-30) and is stored in the MusicAssistant instance as self.safe_mode
• Regular providers are skipped when self.safe_mode is True, while built-in providers always load via _load_builtin_providers()

Frequently Asked Questions

Does safe mode disable the web interface?

No. The web server and core controllers initialize normally in safe mode. Only third-party providers that stream music from external services are bypassed during the startup sequence.

Can I switch to safe mode without restarting Music Assistant?

No. Safe mode is determined at startup in __main__.py and passed to the MusicAssistant constructor. You must restart the server with one of the activation methods (CLI flag, environment variable, or options.json) to enable or disable safe mode.

What providers are considered "built-in" in safe mode?

Built-in providers include core metadata services and essential system providers that are required for basic functionality. These load via _load_builtin_providers() regardless of the safe mode setting, while user-configured streaming providers are handled by _load_providers() and skipped when safe mode is active.

Is safe mode available in the Home Assistant add-on?

Yes. Home Assistant users can enable safe mode by setting "safe_mode": true in the add-on's configuration options without needing to modify environment variables or command-line arguments, making it accessible directly through the Home Assistant UI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}