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

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.

How Safe Mode Controls Provider Loading

The startup logic in 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:

# 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:

# 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, or when the corresponding configuration entry is enabled.

Built-in Providers That Always Load

A provider qualifies as built-in when its 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 and 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 – Contains the core startup routine with the safe mode guard logic around _load_builtin_providers() and _load_providers()
• 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
• Built-in providers identified by "builtin": true in their 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 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 and sets the self.safe_mode attribute to True, which triggers the provider loading restrictions in 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, 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 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.

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