# How to Debug Provider Load Failures in Music Assistant

> Debug provider load failures in Music Assistant. Use last_error, debug_reload_provider tool, and logs to quickly identify and fix issues.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-13

---

**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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/debug.py) executes the following logic:

```python

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

```bash
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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/requirements.txt), correcting credentials in [`config.yaml`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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.