How to Debug Provider Load Failures in Music Assistant

Use the last_error field in the provider configuration and the debug_reload_provider MCP tool to identify and force-reload failed providers while checking logs at $HOME/.musicassistant/musicassistant.log for detailed traceback.

Music Assistant loads each provider—whether a music source, player, or metadata service—through the central MusicAssistant class. When a provider fails to import, instantiate, or initialize, the server captures the exception in the persistent configuration and logs detailed diagnostics. Understanding the load pipeline and the specific locations where errors are recorded allows you to rapidly diagnose why a provider remains unavailable.

Understanding the Provider Load Pipeline

The loading process follows a strict sequence defined in music_assistant/mass.py. Tracing a failure requires following the execution from the entry point through the error handlers.

The pipeline executes as follows:

1. Configuration Resolution – mass.load_provider() retrieves the ProviderConfig for the requested instance_id from the internal registry.

2. Timer Cancellation – Pending reload timers for that provider are cancelled to prevent race conditions during the reload operation.

3. Provider Instantiation – The method calls mass.load_provider_config(), which delegates to the internal _load_provider() helper. This helper dynamically imports the provider module and executes its setup routine.

4. Error Capture – If _load_provider() raises an exception, the except block at lines 33‑40 stores the error string in the configuration field last_error and updates the persistent config.yaml file.

5. Retry Scheduling – For recoverable MusicAssistantError exceptions, the system schedules an automatic retry with a default interval of 2 minutes.

6. Diagnostic Logging – A warning is emitted via LOGGER.warning with full traceback when verbose logging is enabled.

7. Cleanup on Fatal Errors – For fatal exceptions, mass.unload_provider_with_error() executes at lines 99‑102, recording the error and cleaning up the provider instance.

Locating Error Information

When a provider fails to load, three primary sources contain the diagnostic information:

Log Files

The primary log file resides at $HOME/.musicassistant/musicassistant.log. With default settings, you will see a warning line formatted as:

Error loading provider(instance) <name>: <exception>

Start the server with --log-level debug to capture the full stack trace in the exc_info field.

Provider Configuration

The server stores the most recent error message in the runtime configuration. Inspect $HOME/.musicassistant/config.yaml and locate the entry under providers:<instance_id>:last_error. This field contains the exact exception message caught during the last load attempt.

MCP Debug Tool

The FastMCP server implementation includes a specialized debugging utility. Located in music_assistant/providers/fastmcp_server/tools/debug.py, the debug_reload_provider tool forces a provider reload and writes an audit log entry before attempting the operation.

Using the MCP Debug Reload Tool

The debug_reload_provider tool provides a programmatic way to force a provider reload without waiting for the automatic retry timer. This is particularly useful when you have corrected a configuration error or installed a missing dependency.

The tool implementation in debug.py executes the following logic:

# Located in music_assistant/providers/fastmcp_server/tools/debug.py

await mass._load_provider(conf)  # Low-level load that can raise

To invoke the tool via the HTTP API:

curl -X POST http://localhost:8095/api/tools/debug_reload_provider \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "spotify_1"}'

If the load fails, the surrounding error handling in mass.load_provider captures the exception, updates last_error, and logs the failure. Because the tool runs inside the server process, it ensures that even early crashes during module import are recorded in the audit log.

Common Failure Modes and Solutions

Failure Symptom	Likely Cause	Debug Steps
ImportError / ModuleNotFoundError	Missing Python dependency (e.g., ffmpeg-python, yt-dlp).	Verify the provider's requirements.txt and run pip install -r requirements.txt. Confirm with python -c "import <module>".
AuthenticationError	Invalid credentials or expired tokens.	Check last_error for LoginFailedError. Re-enter credentials via the UI or edit config.yaml directly.
NetworkError / Timeout	External API unreachable.	Enable debug logging and monitor the log for HTTP request failures. Verify connectivity with ping or curl from the host.
Unhandled Exception	Bug in provider code (e.g., ValueError from malformed API response).	The stack trace in the log points to the specific line in the provider module (e.g., providers/spotify/provider.py).
Provider Stays Unavailable	The provider raises MusicAssistantError, triggering a 2-minute retry timer.	Use debug_reload_provider to force immediate reload after fixing the underlying issue.

Step-by-Step Debugging Workflow

Follow this systematic approach to resolve provider load failures:

1. Tail the log – Run tail -f $HOME/.musicassistant/musicassistant.log and look for "Error loading provider" messages.

2. Inspect the configuration – Open $HOME/.musicassistant/config.yaml and check the providers:<instance_id>:last_error field for the stored exception message.

3. Enable verbose logging – Restart the server with python -m music_assistant --log-level debug to capture full stack traces.

4. Force a reload – Use the MCP tool to trigger debug_reload_provider for the specific instance ID to test if the issue persists after intervention.

5. Verify dependencies – Run scripts/gen_requirements_all.py to generate a complete list of required packages, then ensure all are installed in the environment.

6. Check network connectivity – Test API endpoints from the host machine to rule out firewall or DNS issues.

Summary

• Provider load failures in Music Assistant are captured in the last_error field of the provider configuration and logged to $HOME/.musicassistant/musicassistant.log.
• The load pipeline in music_assistant/mass.py handles errors through mass.load_provider() and mass.unload_provider_with_error(), with automatic retries for MusicAssistantError every 2 minutes.
• The debug_reload_provider tool in music_assistant/providers/fastmcp_server/tools/debug.py allows forced reloads without waiting for the retry timer.
• Debug logging (--log-level debug) reveals full tracebacks necessary for diagnosing import errors, authentication failures, and network timeouts.
• Common fixes include installing missing dependencies from the provider's requirements.txt, correcting credentials in config.yaml, and verifying network access to external APIs.

Frequently Asked Questions

Where does Music Assistant store provider error messages?

Music Assistant stores the most recent error in the last_error field within the provider's configuration entry in $HOME/.musicassistant/config.yaml. This field is updated whenever mass.load_provider() catches an exception during the load process, providing a persistent record of why the provider failed to initialize.

How can I force a provider to reload without restarting the server?

Use the debug_reload_provider MCP tool provided in music_assistant/providers/fastmcp_server/tools/debug.py. This tool unloads the provider, writes an audit log entry, and re-executes mass._load_provider(). You can call it via the HTTP API at /api/tools/debug_reload_provider with the instance_id as a parameter.

Why does a provider show as "unavailable" even after I fixed the configuration?

If the provider raised a MusicAssistantError (such as a temporary network failure), the system schedules an automatic retry with a 2-minute delay. Until this timer fires or you manually trigger a reload using the MCP debug tool, the provider remains in the unavailable state. Check the last_error field to confirm if the error is marked as retryable.

What log level do I need to see full stack traces for provider failures?

Set the log level to debug when starting the server: python -m music_assistant --log-level debug. At this level, the LOGGER.warning call in mass.load_provider() includes exc_info=exc, which prints the complete Python traceback showing exactly which line in the provider module caused the failure.

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