# How Music Assistant Safe Mode Works and When It Is Activated

> Learn how Music Assistant safe mode functions to skip third-party providers and only run core controllers. Discover activation methods via command-line, add-on options, or environment variables.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: internals
- Published: 2026-06-16

---

**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`](https://github.com/music-assistant/server/blob/main/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:

```bash
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`](https://github.com/music-assistant/server/blob/main/options.json) file:

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

```

### Environment Variable

Export `MASS_SAFE_MODE` with any truthy value before starting the process:

```bash
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`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py):

```python
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:

```python
mass = MusicAssistant(data_dir, cache_dir, safe_mode)

```

Inside [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/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:

```python

# 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`](https://github.com/music-assistant/server/blob/main/options.json) configuration
- The flag evaluation occurs in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/__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.