# How to Debug Issues with Music Assistant Server: A Complete Troubleshooting Guide

> Troubleshoot Music Assistant server issues effectively. Learn to enable verbose logging, monitor logs, and inspect the core class to resolve startup, network, or provider failures.

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

---

**Enable verbose logging with `--log-level verbose`, monitor the log file at `~/.musicassistant/musicassistant.log`, and inspect the core `MusicAssistant` class via Python REPL to isolate startup, networking, or provider failures in your Music Assistant server instance.**

Debugging the Music Assistant server requires understanding its asynchronous architecture built around the core `MusicAssistant` class and aiohttp-based web layer. Whether you are troubleshooting port binding errors, SSL certificate failures, or provider loading issues, the `music-assistant/server` repository provides comprehensive logging and diagnostic hooks. This guide walks through systematic debugging techniques using actual source file paths and runnable code examples from the codebase.

## Locate and Monitor Log Files

Music Assistant writes runtime logs to a rotating file in your user data directory. According to the source in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) (lines 110-120), the `setup_logger()` function initializes a `RotatingFileHandler` that persists logs to `~/.musicassistant/musicassistant.log`.

The same file also configures console output (STDOUT/STDERR) with a `ColoredFormatter` for readable terminal output (lines 84-104).

To monitor logs in real-time:

```bash
tail -f ~/.musicassistant/musicassistant.log

```

If the log file does not exist, the server failed before logger initialization—usually indicating a **Python import error** or missing dependency.

## Enable Verbose Logging for Detailed Diagnostics

The server defines a custom `VERBOSE` log level (numeric value from `constants.VERBOSE_LOG_LEVEL`) that captures detailed diagnostic information beyond standard INFO levels.

To enable verbose logging, start the server with:

```bash
python -m music_assistant --log-level verbose

```

Alternatively, set the environment variable:

```bash
export LOG_LEVEL=verbose
python -m music_assistant

```

The `--log-level` argument is parsed in [`__main__.py`](https://github.com/music-assistant/server/blob/main/__main__.py) (lines 65-70) and passed to `setup_logger()` before the event loop starts.

## Diagnose Common Startup Failures

### Port Binding Errors

If you see the error **"Could not bind to 0.0.0.0, will start on all interfaces"** in your logs, the server cannot attach to the specified network interface. This occurs in [`music_assistant/helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py) (lines 107-110) when the `TCPSite` fails to start.

Verify the port is available:

```bash
lsof -i :8095

# or start with alternative binding

python -m music_assistant --bind-ip 127.0.0.1 --bind-port 8080

```

### Import Errors and Missing Dependencies

An `ImportError: cannot import name 'Webserver'` typically indicates a broken virtual environment or missing `aiohttp` dependency. The [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) file contains the exact `pip install -r requirements.txt` command used to establish a clean environment.

### Provider Loading Failures

During startup, `MusicAssistant.__load_provider_manifests()` (called from `MusicAssistant.start()` in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py)) iterates over provider directories and logs parsing errors at ERROR level. Search your logs for `provider` or `manifest` to identify invalid JSON or missing dependencies in `music_assistant/providers/<name>/manifest.json`.

## Inspect Runtime State via Python REPL

You can introspect a running or temporary instance by instantiating the `MusicAssistant` class directly from [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) (lines 10-30). This is useful for verifying controller initialization and provider registration.

```python
import asyncio
from music_assistant import MusicAssistant

async def dump_state():
    ma = MusicAssistant(
        storage_path="~/.musicassistant",
        cache_path="~/.musicassistant/.cache"
    )
    await ma.start()
    print("Version:", ma.version)
    print("Loaded providers:", list(ma.providers.keys()))
    print("Webserver URL:", ma.webserver.base_url)
    await ma.stop()

asyncio.run(dump_state())

```

The `webserver` attribute is an instance of `WebserverController` (defined in [`music_assistant/controllers/webserver/controller.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/controller.py), lines 99-106), which wraps the low-level aiohttp implementation.

## Debug the HTTP API and WebSocket Layer

Verify the server is responsive by checking the health endpoint:

```bash
curl -s http://localhost:8095/api/health | jq .

```

A JSON response with `"status":"ok"` confirms the aiohttp server in [`music_assistant/helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py) is accepting connections.

To trace individual requests, temporarily add middleware logging in [`helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/helpers/webserver.py):

```python
async def _log_request(request, handler):
    request.app.logger.debug("Request: %s %s", request.method, request.path)
    return await handler(request)

# Inside Webserver.setup, before route registration:

self._webapp.middlewares.append(_log_request)

```

## Troubleshoot SSL and Certificate Verification

SSL verification is handled by `verify_ssl_certificate()` in [`music_assistant/controllers/webserver/helpers/ssl.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/helpers/ssl.py). When you trigger the **Verify SSL** action in the UI, `WebserverController.get_config_entries()` (lines 135-142) calls this helper and returns a dataclass with fields `valid`, `subject`, `issuer`, and `expiration`.

The result is logged at INFO level and displayed as a toast notification. For additional detail, temporarily add debug logging in [`helpers/ssl.py`](https://github.com/music-assistant/server/blob/main/helpers/ssl.py):

```python
self.logger.debug("SSL cert info: %s", cert_info)

```

## Diagnose Provider Configuration Problems

Each provider resides under `music_assistant/providers/<name>/` with a [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) describing required configuration. To test dynamic loading:

```python
from music_assistant.helpers.util import load_provider_module
module = load_provider_module("spotify")  # example provider name

print(dir(module))

```

If the module raises an exception, the stack trace appears in the log with the prefix `Provider load error:`.

## Capture Minimal Reproduction Cases

When reporting issues, include these elements to expedite resolution:

1. **Exact command line** used to start MA (including environment variables)
2. **Relevant log excerpt** using `grep -C 5 "<error-keyword>" ~/.musicassistant/musicassistant.log`
3. **Steps to reproduce** (e.g., "open `/api/player/play` after enabling SSL")
4. **Python version** (`python -VV`) and **OS** (`uname -a`)
5. **Minimal reproduction script** (such as the REPL snippet above)

## Summary

- Monitor the rotating log file at `~/.musicassistant/musicassistant.log` to catch startup errors configured in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py)
- Use `--log-level verbose` or set `LOG_LEVEL=verbose` to enable detailed diagnostic output from the custom log level
- Check [`music_assistant/helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py) for port binding issues and [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) for dependency verification
- Inspect runtime state by instantiating the `MusicAssistant` class from [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) in a Python REPL
- Verify SSL certificates using the `verify_ssl_certificate` function in [`music_assistant/controllers/webserver/helpers/ssl.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/helpers/ssl.py)
- Examine provider manifests in `music_assistant/providers/<name>/` and check `__load_provider_manifests()` logs to debug loading failures

## Frequently Asked Questions

### How do I enable debug logging in Music Assistant server?

Enable debug logging by starting the server with `python -m music_assistant --log-level verbose` or setting the environment variable `export LOG_LEVEL=verbose` before execution. This activates the custom `VERBOSE` log level defined in the constants module and is parsed in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) before the logger initializes.

### Where does Music Assistant store its log files?

Music Assistant writes runtime logs to `~/.musicassistant/musicassistant.log` using a `RotatingFileHandler` configured in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) (lines 110-120). If this file does not exist, the server likely failed before logger initialization, usually due to a Python import error or missing dependency.

### Why is Music Assistant failing to start on port 8095?

Port binding failures occur when the address is already in use or the process lacks sufficient privileges. Check [`music_assistant/helpers/webserver.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py) lines 107-110 for the error message "Could not bind to 0.0.0.0", and verify no other process is using the port with `lsof -i :8095` or start with `--bind-port` to specify an alternative.

### How can I verify my SSL certificate configuration?

Use the **Verify SSL** action in the UI or CLI, which triggers `verify_ssl_certificate()` in [`music_assistant/controllers/webserver/helpers/ssl.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/helpers/ssl.py) (called from `WebserverController.get_config_entries()` at lines 135-142). The function returns a dataclass with `valid`, `subject`, `issuer`, and `expiration` fields, which are logged at INFO level and displayed in the interface.