# How Safe Mode Impacts Provider Loading in Music Assistant: Built-in Providers That Always Load

> Discover how Safe Mode impacts provider loading in Music Assistant. Learn which built-in providers always load for core functionality, even when external ones are disabled.

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

---

**Safe mode in Music Assistant disables all external providers while forcing built-in providers to load unconditionally, ensuring core metadata, audio analysis, and local playback functionality remain available for debugging core controllers.**

Music Assistant is an open-source media server that organizes audio sources into modular provider components. When troubleshooting core system issues, administrators can start the server in safe mode to isolate problems, but this mode specifically controls which providers initialize during the startup sequence defined in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py).

## How Safe Mode Controls Provider Loading

The startup logic in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) separates providers into two distinct loading phases based on the `self.safe_mode` boolean flag.

When the server initializes, it first loads all core controllers (cache, tasks, streams, music, metadata, and players). Then it handles provider loading through two separate method calls:

```python

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

await self._load_builtin_providers()

```

Immediately after, the server checks the safe mode state before loading external integrations:

```python

# load regular providers (skip when in safe mode)

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

```

The `self.safe_mode` attribute is set to `True` when the `--safe-mode` command-line flag is passed via [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py), or when the corresponding configuration entry is enabled.

## Built-in Providers That Always Load

A provider qualifies as built-in when its [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) contains `"builtin": true`. These providers load unconditionally because they provide essential functionality required for core operations.

According to the repository's provider manifests, the following built-in providers always initialize even in safe mode:

- **`builtin`** – Internal helper provider used by many other providers for core utility functions
- **`wikipedia`** – Metadata provider for multi-lingual artist biographies and descriptive text
- **`universal_player`** – Generic player implementation for basic playback control
- **`theaudiodb`** – MusicBrainz-style metadata source for audio information
- **`sync_group`** – Player provider that synchronizes multiple players into a single group
- **`sendspin`** – Metadata provider for the SendSpin service
- **`musicbrainz`** – Central music metadata database integration
- **`lrclib`** – Lyrics and timestamp provider for synchronized lyrics
- **`loudness_analysis`** – Audio analysis provider for track loudness and volume normalization
- **`local_audio`** – Music provider for accessing locally stored audio files
- **`itunes_artwork`** – Metadata provider for retrieving album artwork from iTunes
- **`fanarttv`** – High-quality fan-art images for artists and albums
- **`coverartarchive`** – Archive of album covers from the Internet Archive

Each provider declares its status in its manifest file, such as [`music_assistant/providers/wikipedia/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/wikipedia/manifest.json) and [`music_assistant/providers/musicbrainz/manifest.json`](https://github.com/music-assistant/server/blob/main/music_assistant/providers/musicbrainz/manifest.json), where the `"builtin": true` flag determines this unconditional loading behavior.

## What Gets Disabled in Safe Mode

When `self.safe_mode` is `True`, the server skips the `_load_providers()` call entirely. This prevents initialization of any provider with `"builtin": false` in its manifest.

**Disabled providers include:**

- Spotify, Plex, and other third-party music services
- Hardware integrations like Sonos and Chromecast
- External metadata services beyond the built-in set
- YouTube and other streaming platforms

This isolation allows administrators to verify core controller functionality without interference from external API dependencies or hardware-specific code paths.

## Key Source Files and Implementation Details

Understanding the safe mode implementation requires familiarity with these specific files:

- **[`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py)** – Contains the core startup routine with the safe mode guard logic around `_load_builtin_providers()` and `_load_providers()`
- **[`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py)** – Parses the `--safe-mode` CLI flag and initializes the `safe_mode` attribute on the MusicAssistant instance
- **`music_assistant/providers/*/manifest.json`** – Each provider's manifest declares the `"builtin"` boolean flag that determines loading eligibility

The manifest system provides the declarative boundary between essential and optional functionality, allowing the server to distinguish between core infrastructure and extended features.

## Summary

- **Safe mode** disables external provider loading by skipping the `_load_providers()` call in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py)
- **Built-in providers** identified by `"builtin": true` in their [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) files load unconditionally via `_load_builtin_providers()`
- **Thirteen built-in providers** always load, including metadata services (MusicBrainz, Wikipedia), audio analysis (loudness_analysis), and local playback (local_audio, universal_player)
- **External providers** like Spotify, Sonos, and YouTube are skipped, creating an isolated environment for debugging core controllers
- The `--safe-mode` CLI flag in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) triggers this behavior by setting `self.safe_mode` to `True`

## Frequently Asked Questions

### How do I enable safe mode in Music Assistant?

Start the Music Assistant server with the `--safe-mode` command-line flag, or enable the corresponding safe mode configuration entry in your settings. This flag is processed in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and sets the `self.safe_mode` attribute to `True`, which triggers the provider loading restrictions in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py).

### Why do built-in providers load when safe mode is enabled?

Built-in providers load unconditionally because they provide essential infrastructure required for core functionality. According to the source code in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py), the `_load_builtin_providers()` method executes regardless of the safe mode state, ensuring metadata resolution, local audio handling, and audio analysis capabilities remain available for debugging.

### Can I use streaming services like Spotify in safe mode?

No. Streaming services like Spotify, Plex, and YouTube are regular providers with `"builtin": false` in their manifests. When safe mode is active, the server skips the `_load_providers()` call that initializes these external integrations, leaving only the thirteen built-in providers active.

### How can I tell if a provider is built-in or external?

Check the provider's [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) file in the `music_assistant/providers/` directory. If the manifest contains `"builtin": true`, the provider loads in safe mode. If the field is `false` or absent, the provider is considered external and only loads when safe mode is disabled.